@zmice/zc 0.2.8 → 0.3.0

package/vendor/packages/toolkit/src/content/skills/multi-perspective-review/body.md

@@ -1,81 +1,129 @@
-# 多视角评审
-
-## 何时使用
-
-- Spec 或 Plan 写完、实现还没开始时
-- 架构决策牵涉产品、工程、设计和开发体验多个面向时
-- 团队觉得方案“好像没问题”，但还没经过压力测试时
-- 需要尽早发现范围、体验或维护性盲区时
-
-## 输入前提
-
-- 已有可评审的规格、计划或方案草案
-- 愿意在实现前先暴露问题
-- 接受同一个方案需要经过多种视角拷问
-- 明确这里评审的是“计划态假设”，不是实现后的真实走查
-
-## 执行步骤
-
-1. 用 **产品视角** 检查是否在解决正确问题
-2. 用 **工程视角** 检查架构、数据流、状态、失败模式、边界条件、性能和测试策略
-3. 用 **设计视角** 检查交互、可用性、响应式和无障碍
-4. 用 **DevEx 视角** 检查计划中的集成成本、配置复杂度、文档前提、学习曲线和维护负担
-5. 把四个视角发现的问题改写成可执行的修订项、约束或验收标准
-6. 汇总结论，明确需要修订的点，再决定是否进入实现
-
-## 评审产物
-
-评审结果必须能回写到 plan / spec，而不是只形成聊天意见：
-
-- `GO / REVISE / NO-GO` 结论
-- 分级发现：`Critical / Warning / Suggestion`
-- 每条发现对应的证据、影响和修订动作
-- 对应的验收标准或验证命令
-- 如果需要提问，最多 1-3 个会改变方案的关键问题
-
-## 推荐结论格式
-
-最终结论必须包含明确推荐和取舍：
-
-```text
-Recommendation: <GO / REVISE / NO-GO + next action> because <specific cross-perspective trade-off>.
-```
-
-推荐理由至少说明：
-
-- 哪个视角的证据最关键
-- 放弃了什么替代方案
-- 接受了什么代价或风险
-- 下一步用什么验证或修订来收敛
-
-如果需要提问，每个问题都要说明它会解锁哪个决策，避免只收集背景信息。
-
-## 边界说明
-
-- 这里的 DevEx 只评估“实现前是否想清楚”，不替代实现后的真实安装和上手走查
-- 如果代码已经落地，需要确认 getting started、安装链和首次成功路径是否真的成立，转到 `developer-experience-audit`
-- 不要把这里当成发布前体验签收清单；它的价值是提前暴露盲点，而不是事后补测
-- 不引入重型运行时、遥测、自动升级或跨会话记忆作为评审前提；这些只能作为显式 opt-in 的后续能力讨论
-
-## 成功标准
-
-- 方案不再只从工程角度自证合理
-- 关键风险能在写代码前暴露
-- 每个视角都有具体 concern，而不是泛泛评价
-- DevEx 问题被表达为计划假设、约束或验收条件，而不是模糊感受
-- 最终结论可以明确是 `GO / REVISE / NO-GO`
-- 评审输出能直接变成 plan 修订、任务依赖或验证门禁
-
-## 相关原则
-
-- 越早发现问题，修复成本越低
-- 单一视角的“没问题”不算通过
-- 评审输出必须能转化为具体修订动作
-- 计划态评审与实现后实测必须分相位处理
-
-## 与其他技能的衔接
-
-- 常接在 `spec-driven-development` 或 `planning-and-task-breakdown` 之后
-- 评审通过后再进入 `incremental-implementation`
-- 实现完成后，如需验证 DevEx 假设是否成立，继续进入 `developer-experience-audit`
-- 产品或架构争议较大时，可结合 `product-owner` 和 `architect`
+# 多视角评审
+
+## 何时使用
+
+- Spec 或 Plan 写完、实现还没开始时
+- 架构决策牵涉产品、工程、设计和开发体验多个面向时
+- 团队觉得方案“好像没问题”，但还没经过压力测试时
+- 需要尽早发现范围、体验或维护性盲区时
+
+## 输入前提
+
+- 已有可评审的规格、计划或方案草案
+- 愿意在实现前先暴露问题
+- 接受同一个方案需要经过多种视角拷问
+- 明确这里评审的是“计划态假设”，不是实现后的真实走查
+
+## 执行步骤
+
+1. 用 **产品视角** 检查是否在解决正确问题
+2. 用 **工程视角** 检查架构、数据流、状态、失败模式、边界条件、性能和测试策略
+3. 用 **设计视角** 检查交互、可用性、响应式和无障碍
+4. 用 **DevEx 视角** 检查计划中的集成成本、配置复杂度、文档前提、学习曲线和维护负担
+5. 把四个视角发现的问题改写成可执行的修订项、约束或验收标准
+6. 对会改变路线的发现触发 `stop gate`，先收敛决策，不把问题静默写进计划后继续
+7. 输出 `Implementation Tasks`，把需要修订的发现转成可执行任务
+8. 汇总结论，明确需要修订的点，再决定是否进入实现
+
+## 评审产物
+
+评审结果必须能回写到 plan / spec，而不是只形成聊天意见：
+
+- `GO / REVISE / NO-GO` 结论
+- 分级发现：`Critical / Warning / Suggestion`
+- 每条发现对应的证据、影响和修订动作
+- 对应的验收标准或验证命令
+- 会改变路线的 stop gate 决策及当前状态
+- `Implementation Tasks`：每条待修问题对应的 P1/P2/P3 任务
+- 如果需要提问，最多 1-3 个会改变方案的关键问题
+
+## 推荐结论格式
+
+最终结论必须包含明确推荐和取舍：
+
+```text
+Recommendation: <GO / REVISE / NO-GO + next action> because <specific cross-perspective trade-off>.
+```
+
+推荐理由至少说明：
+
+- 哪个视角的证据最关键
+- 放弃了什么替代方案
+- 接受了什么代价或风险
+- 下一步用什么验证或修订来收敛
+
+如果需要提问，每个问题都要说明它会解锁哪个决策，避免只收集背景信息。
+
+## Stop Gate
+
+以下情况不能直接给 `GO`：
+
+- Critical 发现会改变架构、数据模型、权限、破坏性操作或用户可见承诺
+- 不同视角的结论互相冲突，且会改变任务顺序或验收标准
+- 计划缺少关键验证方式，导致实现完成后无法判定是否通过
+- 发现明显过度设计，但当前计划仍按高复杂度方案推进
+
+Stop gate 输出：
+
+```text
+STOP: <route-changing finding>
+- Perspective:
+- Evidence:
+- Impact:
+- Options:
+- Recommendation:
+- Required decision or assumption:
+```
+
+如果用户已给出偏好，写成 `Assumption` 并继续；否则先提问。不要把 stop gate 伪装成普通 Suggestion。
+
+## Implementation Tasks
+
+评审发现必须能转成 plan 可吸收的任务：
+
+```text
+### Implementation Tasks
+- [ ] T1 (P1) — <component> — <imperative title>
+  - Surfaced by: <perspective> — <specific finding>
+  - Files likely touched:
+  - Acceptance criteria:
+  - Verification:
+```
+
+规则：
+
+- P1 阻塞进入实现或合并
+- P2 应进入当前计划
+- P3 可以作为 follow-up，但要说明不阻塞的理由
+- 没有 actionable task 的发现，要明确写 `_No implementation task; informational only._`
+
+## 边界说明
+
+- 这里的 DevEx 只评估“实现前是否想清楚”，不替代实现后的真实安装和上手走查
+- 如果代码已经落地，需要确认 getting started、安装链和首次成功路径是否真的成立，转到 `developer-experience-audit`
+- 不要把这里当成发布前体验签收清单；它的价值是提前暴露盲点，而不是事后补测
+- 不引入重型运行时、遥测、自动升级或跨会话记忆作为评审前提；这些只能作为显式 opt-in 的后续能力讨论
+
+## 成功标准
+
+- 方案不再只从工程角度自证合理
+- 关键风险能在写代码前暴露
+- 每个视角都有具体 concern，而不是泛泛评价
+- DevEx 问题被表达为计划假设、约束或验收条件，而不是模糊感受
+- 最终结论可以明确是 `GO / REVISE / NO-GO`
+- 评审输出能直接变成 plan 修订、任务依赖或验证门禁
+- Critical 或 route-changing 发现没有被跳过；要么进入 stop gate，要么转成 P1 任务
+
+## 相关原则
+
+- 越早发现问题，修复成本越低
+- 单一视角的“没问题”不算通过
+- 评审输出必须能转化为具体修订动作
+- 计划态评审与实现后实测必须分相位处理
+
+## 与其他技能的衔接
+
+- 常接在 `spec-driven-development` 或 `planning-and-task-breakdown` 之后
+- 评审通过后再进入 `incremental-implementation`
+- 实现完成后，如需验证 DevEx 假设是否成立，继续进入 `developer-experience-audit`
+- 产品或架构争议较大时，可结合 `product-owner` 和 `architect`

package/vendor/packages/toolkit/src/content/skills/parallel-agent-dispatch/body.md

@@ -1,113 +1,143 @@
-# Parallel Agent Dispatch
-
-## 角色定位
-
-在用户明确允许多 agent / 并行 / team 模式时，把彼此独立的任务做上下文级 fan-out，并在结束时做 fan-in、冲突检测和集成验证。
-
-这个 skill 不是默认加速器。能并行不等于应该并行；并行会增加 token、延迟、集成和验证成本。
-
-## 快速路径
-
-1. 读取计划，列出所有任务、依赖和预计触达文件。
-2. 判断任务是否彼此独立，是否有清晰文件所有权。
-3. 给出并行推荐，但在用户明确确认前不启动子代理。
-4. 为每个 worker 分配唯一责任范围、允许修改文件和验证命令。
-5. fan-out 执行，期间不让多个 worker 修改同一文件。
-6. fan-in 汇总，检查 diff、冲突、接口一致性和测试结果。
-7. 记录验收 transcript：谁做了什么、证据是什么、还有什么风险。
-
-## 使用条件
-
-适用：
-
-- 多个任务互不依赖。
-- 每个任务能在独立上下文中完成。
-- 文件所有权可以提前划清。
-- fan-in 后有集成测试或人工审查门禁。
-
-不适用：
-
-- 任务依赖同一个未完成设计。
-- 多个任务必须改同一文件。
-- 缺少测试或集成验证方式。
-- 用户没有明确授权并行。
-
-## 模式选择
-
-| 模式 | 适用场景 | 代价 |
-|---|---|---|
-| Context Fan-Out | 只需要多个子代理分别分析或修改互不重叠文件 | 共享同一 worktree，fan-in 需谨慎检查 |
-| Worktree Parallel | 任务可能触及相邻区域，或需要独立构建环境 | 需要分支和 worktree 清理 |
-| Cascade | 任务有层级依赖，但每层内可并行 | 每层都要验证后再进下一层 |
-| Team Orchestration | 需要 tmux + git worktree + 多 CLI worker | 运行时成本最高，需 `zc team` 收尾 |
-
-如果需要文件系统级隔离，切到 `team-orchestration`；不要在本 skill 内展开完整 `zc team` 教程。
-
-## 授权提示
-
-启动前必须给用户看到这段信息的等价内容：
-
-```text
-Recommendation: 开启 <模式> because <并行收益> outweighs <集成代价>。
-- worker 数：
-- 文件所有权：
-- 不并行的替代方案：
-- fan-in 验证：
-
-确认后我再启动；不确认则按串行推进。
-```
-
-## Worker 合约
-
-每个子代理都必须收到：
-
-- 任务目标和验收标准
-- 允许读取的关键上下文
-- 允许修改的文件或模块边界
-- 不得触碰其他 worker 文件的说明
-- 任务内验证命令
-- 返回格式：`DONE / BLOCKED / NEEDS_CONTEXT`
-
-返回时必须列出：
-
-- 修改文件
-- 已运行验证
-- 未覆盖风险
-- 需要主线程 fan-in 的事项
-
-## Fan-In 门禁
-
-并行完成不等于任务完成。fan-in 必须检查：
-
-- 所有子代理结果是否到齐。
-- 是否出现同文件修改、命名冲突或接口冲突。
-- 局部验证是否可信。
-- 主线程是否运行集成测试或目标平台验证。
-- 是否需要清理分支、worktree、临时文件或保留待审查分支。
-
-推荐记录格式：
-
-```text
-Parallel acceptance transcript:
-- Plan:
-- Workers:
-- Files:
-- Results:
-- Verification:
-- Conflicts:
-- Follow-up:
-```
-
-## 失败处理
-
-- 单个 worker 失败时，不要自动丢弃其他成功结果。
-- 先收集成功结果，再判断是否可以部分合入。
-- 失败任务优先缩小范围、补上下文或改为串行处理。
-- 如果失败暴露计划不成立，回到 `planning-and-task-breakdown`。
-
-## 与相关技能的边界
-
-- `subagent-driven-development`：串行委派，不做并行 fan-out。
-- `team-orchestration`：进程级 + 文件系统级隔离。
-- `branch-finish-and-cleanup`：fan-in 后处理分支、worktree 和残留状态。
-- `verification-before-completion`：声明完成前读取验证输出。
+# Parallel Agent Dispatch
+
+## 角色定位
+
+把彼此独立的任务做上下文级 fan-out，并在结束时做 fan-in、冲突检测和集成验证。只读 fan-out 只有在用户已授权本会话或项目默认启用只读 agent 时，才可通知式启动；写入型 fan-out 必须先确认文件所有权、验证命令和 fan-in gate。
+
+这个 skill 不是默认加速器。能并行不等于应该并行；并行会增加 token、延迟、集成和验证成本。
+
+## 快速路径
+
+1. 读取计划，列出所有任务、依赖和预计触达文件。
+2. 判断任务是否彼此独立，是否有清晰文件所有权。
+3. 区分只读通知式 fan-out 和写入确认式 fan-out。
+4. 为每个 worker 分配唯一责任范围、允许读取或修改的边界和验证命令。
+5. fan-out 执行，期间不让多个写入 worker 修改同一文件。
+6. fan-in 汇总，检查 diff、冲突、接口一致性、review finding 和回归结果。
+7. 记录验收 transcript：谁做了什么、谁提出了什么、谁修复了什么、谁回归了什么、证据是什么、还有什么风险。
+
+## 使用条件
+
+适用：
+
+- 多个任务互不依赖。
+- 每个任务能在独立上下文中完成。
+- 写入任务的文件所有权可以提前划清，或只读任务有明确问题边界。
+- fan-in 后有集成测试或人工审查门禁。
+
+不适用：
+
+- 任务依赖同一个未完成设计。
+- 多个任务必须改同一文件。
+- 缺少测试或集成验证方式。
+- 写入型并行没有用户确认。
+
+## 模式选择
+
+| 模式 | 适用场景 | 代价 |
+|---|---|---|
+| Readonly Consult | 多个只读 agent 分别评估架构、测试、安全、性能、产品或 review 风险 | 需要主线程判断哪些结论成立 |
+| Context Fan-Out | 只需要多个子代理分别分析或修改互不重叠文件 | 共享同一 worktree，fan-in 需谨慎检查 |
+| Worktree Parallel | 任务可能触及相邻区域，或需要独立构建环境 | 需要分支和 worktree 清理 |
+| Cascade | 任务有层级依赖，但每层内可并行 | 每层都要验证后再进下一层 |
+| Team Orchestration | 需要 tmux + git worktree + 多 CLI worker | 运行时成本最高，需 `zc team` 收尾 |
+
+如果需要文件系统级隔离，切到 `team-orchestration`；不要在本 skill 内展开完整 `zc team` 教程。
+
+## 通知与授权
+
+只读 fan-out 在已授权时使用通知式提示：
+
+```text
+Agent assist:
+- <agent>：只读评估 <范围>，不改文件
+fan-in：主线程汇总结论后再决定是否改代码
+```
+
+如果当前会话或项目没有只读 agent 默认授权，只输出上面的 `Agent assist` 预告并等待确认。
+
+写入型 fan-out 启动前必须给用户看到这段信息的等价内容：
+
+```text
+Recommendation: 开启 <模式> because <并行收益> outweighs <集成代价>。
+- worker 数：
+- 文件所有权：
+- 不并行的替代方案：
+- fan-in 验证：
+
+确认后我再启动；不确认则按串行推进。
+```
+
+默认上限：
+
+- 普通复杂任务最多 1 个只读 agent。
+- 跨模块或高风险任务最多 2 个只读 agent。
+- 写入型并行默认最多 2 个 worker。
+- 超过 2 个 worker 必须说明收益和 fan-in 成本。
+- `zc team` 必须用户明确要求或确认。
+
+## Worker 合约
+
+每个子代理都必须收到：
+
+- 任务目标和验收标准
+- 允许读取的关键上下文
+- 允许修改的文件或模块边界；只读 worker 必须明确“不改文件”
+- 不得触碰其他 worker 文件的说明
+- 任务内验证命令
+- 返回格式：`DONE / BLOCKED / NEEDS_CONTEXT`
+
+返回时必须列出：
+
+- 修改文件
+- 已运行验证
+- 提出的 findings 或回归结论
+- 未覆盖风险
+- 需要主线程 fan-in 的事项
+
+## Fan-In 门禁
+
+并行完成不等于任务完成。fan-in 必须检查：
+
+- 所有子代理结果是否到齐。
+- 是否出现同文件修改、命名冲突或接口冲突。
+- 局部验证是否可信。
+- review finding 是否由提出方完成回归。
+- 主线程是否运行集成测试或目标平台验证。
+- 是否需要清理分支、worktree、临时文件或保留待审查分支。
+
+闭环所有权：
+
+- `producer owns fix`：谁引入问题，谁优先修复。
+- `reviewer owns regression`：谁提出问题，谁负责复验原 finding 是否关闭。
+- `controller owns fan-in`：主线程负责接受、转派、整合和最终验证。
+
+推荐记录格式：
+
+```text
+Parallel acceptance transcript:
+- Plan:
+- Workers:
+- Files:
+- Findings:
+- Fixes:
+- Regression:
+- Results:
+- Verification:
+- Conflicts:
+- Follow-up:
+```
+
+## 失败处理
+
+- 单个 worker 失败时，不要自动丢弃其他成功结果。
+- 先收集成功结果，再判断是否可以部分合入。
+- 失败任务优先缩小范围、补上下文或改为串行处理。
+- 如果失败暴露计划不成立，回到 `planning-and-task-breakdown`。
+
+## 与相关技能的边界
+
+- `subagent-driven-development`：串行委派，不做并行 fan-out。
+- `team-orchestration`：进程级 + 文件系统级隔离。
+- `branch-finish-and-cleanup`：fan-in 后处理分支、worktree 和残留状态。
+- `verification-before-completion`：声明完成前读取验证输出。

package/vendor/packages/toolkit/src/content/skills/performance-optimization/body.md

@@ -1,75 +1,75 @@
-# Performance Optimization
-
-## 角色定位
-
-性能优化必须从测量开始。这个 skill 用于定位真实瓶颈、做最小修复、再次测量，并补回归保护；不用于凭感觉提前复杂化实现。
-
-## 何时使用
-
-- 规格里有明确性能目标或预算。
-- 用户、监控或日志报告慢。
-- Core Web Vitals、接口延迟、吞吐、内存或 CPU 有异常。
-- 怀疑一次变更造成性能回归。
-- 功能会处理大数据量、高并发或关键首屏路径。
-
-不适用：没有性能证据，只是担心未来可能慢。
-
-## 快速路径
-
-1. 写清性能症状和目标指标。
-2. 建立 baseline：真实数据或可复现 synthetic 测量。
-3. 定位瓶颈：前端、后端、数据库、网络、渲染、内存或外部依赖。
-4. 只修当前证据指向的瓶颈。
-5. 再次测量，确认指标改善。
-6. 评估复杂度代价，避免为了小收益引入长期维护成本。
-7. 加 guard：监控、benchmark、预算或回归测试。
-
-## 指标选择
-
-| 场景 | 优先指标 |
-|---|---|
-| 首屏慢 | LCP、TTFB、bundle size、network waterfall |
-| 交互卡顿 | INP、long task、render count、main thread profile |
-| 布局跳动 | CLS、图片尺寸、字体加载、late content |
-| API 慢 | p95/p99 latency、query time、cache hit、payload size |
-| 资源异常 | CPU、memory、GC、connection pool、queue depth |
-
-默认使用能复现症状的最小指标。不要同时优化所有指标。
-
-## 常见定位方向
-
-- 前端首屏：大图片、render-blocking CSS/JS、bundle 过大、慢 TTFB。
-- 前端交互：长任务、重复渲染、过大 DOM、同步计算。
-- 数据加载：瀑布请求、N+1、过大 payload、缺少分页。
-- 后端接口：缺索引、锁等待、连接池耗尽、重复计算。
-- 内存/CPU：无界缓存、泄漏、正则回溯、同步重计算。
-
-## 修复纪律
-
-- 先证明瓶颈，再改代码。
-- 一次只优化一个瓶颈。
-- 保留 before / after 数字。
-- 小收益大复杂度的优化要默认拒绝。
-- 性能关键路径改动要补 benchmark、监控或预算门禁。
-
-## 输出契约
-
-```text
-Performance evidence:
-- Symptom:
-- Target:
-- Baseline:
-- Bottleneck:
-- Change:
-- After:
-- Regression guard:
-- Trade-off:
-```
-
-推荐结论：
-
-```text
-Recommendation: <optimize / monitor / defer / revert> because <baseline, measured impact, complexity cost, and rejected alternative>.
-```
-
-没有 baseline 和 after 数据，不要声明性能优化成立。
+# Performance Optimization
+
+## 角色定位
+
+性能优化必须从测量开始。这个 skill 用于定位真实瓶颈、做最小修复、再次测量，并补回归保护；不用于凭感觉提前复杂化实现。
+
+## 何时使用
+
+- 规格里有明确性能目标或预算。
+- 用户、监控或日志报告慢。
+- Core Web Vitals、接口延迟、吞吐、内存或 CPU 有异常。
+- 怀疑一次变更造成性能回归。
+- 功能会处理大数据量、高并发或关键首屏路径。
+
+不适用：没有性能证据，只是担心未来可能慢。
+
+## 快速路径
+
+1. 写清性能症状和目标指标。
+2. 建立 baseline：真实数据或可复现 synthetic 测量。
+3. 定位瓶颈：前端、后端、数据库、网络、渲染、内存或外部依赖。
+4. 只修当前证据指向的瓶颈。
+5. 再次测量，确认指标改善。
+6. 评估复杂度代价，避免为了小收益引入长期维护成本。
+7. 加 guard：监控、benchmark、预算或回归测试。
+
+## 指标选择
+
+| 场景 | 优先指标 |
+|---|---|
+| 首屏慢 | LCP、TTFB、bundle size、network waterfall |
+| 交互卡顿 | INP、long task、render count、main thread profile |
+| 布局跳动 | CLS、图片尺寸、字体加载、late content |
+| API 慢 | p95/p99 latency、query time、cache hit、payload size |
+| 资源异常 | CPU、memory、GC、connection pool、queue depth |
+
+默认使用能复现症状的最小指标。不要同时优化所有指标。
+
+## 常见定位方向
+
+- 前端首屏：大图片、render-blocking CSS/JS、bundle 过大、慢 TTFB。
+- 前端交互：长任务、重复渲染、过大 DOM、同步计算。
+- 数据加载：瀑布请求、N+1、过大 payload、缺少分页。
+- 后端接口：缺索引、锁等待、连接池耗尽、重复计算。
+- 内存/CPU：无界缓存、泄漏、正则回溯、同步重计算。
+
+## 修复纪律
+
+- 先证明瓶颈，再改代码。
+- 一次只优化一个瓶颈。
+- 保留 before / after 数字。
+- 小收益大复杂度的优化要默认拒绝。
+- 性能关键路径改动要补 benchmark、监控或预算门禁。
+
+## 输出契约
+
+```text
+Performance evidence:
+- Symptom:
+- Target:
+- Baseline:
+- Bottleneck:
+- Change:
+- After:
+- Regression guard:
+- Trade-off:
+```
+
+推荐结论：
+
+```text
+Recommendation: <optimize / monitor / defer / revert> because <baseline, measured impact, complexity cost, and rejected alternative>.
+```
+
+没有 baseline 和 after 数据，不要声明性能优化成立。