@zmice/zc 0.2.8 → 0.3.0

package/vendor/packages/toolkit/src/content/skills/subagent-driven-development/body.md

@@ -2,12 +2,25 @@
 
 ## Overview
 
-通过为每个任务分派独立的子代理来执行实现计划，每个任务完成后进行两阶段审查：先验证规格合规性，再验证代码质量。
+通过为每个任务分派独立的子代理来执行实现计划，每个任务完成后进行两阶段审查：先验证规格合规性，再验证代码质量。主线程负责控制计划、分派、fan-in 和最终验证。
 
 **核心原则：每任务一个新子代理 + 两阶段审查 = 高质量 + 快速迭代**
 
 为什么要用子代理：你将任务委派给隔离上下文的专门代理。通过精心构造它们的指令和上下文，确保它们专注且成功。子代理不应继承你的会话上下文 — 你精确构造它们所需的一切。这也保护你自己的上下文用于协调工作。
 
+管控原则：
+
+```text
+producer owns fix
+reviewer owns regression
+controller owns fan-in
+```
+
+- 主线程是 controller / integrator，负责目标、计划、分派、文件所有权、stop gate、fan-in 和最终验证。
+- 实现方或产生方负责优先修复自己引入的问题。
+- 审查方或提出方负责给出复现条件、断言、期望行为和风险等级，并在修复后回归确认。
+- 主线程判断 finding 是否成立、是否阻塞、是否需要转派或降级。
+
 ## When to Use
 
 决策树：
@@ -54,13 +67,13 @@ parallel-agent-dispatch
 │                                                      │
 │  2. 分派规格审查子代理                                │
 │     │                                                │
-│     ├─ 规格不合规？ → 实现者修复 → 重新审查           │
+│     ├─ 规格不合规？ → 实现者修复 → 提出方回归         │
 │     │                                                │
 │     └─ 规格合规 ✓                                    │
 │                                                      │
 │  3. 分派代码质量审查子代理                            │
 │     │                                                │
-│     ├─ 质量不过关？ → 实现者修复 → 重新审查           │
+│     ├─ 质量不过关？ → 实现者修复 → 提出方回归         │
 │     │                                                │
 │     └─ 质量通过 ✓                                    │
 │                                                      │
@@ -110,6 +123,7 @@ parallel-agent-dispatch
 - 是否有超出规格的额外实现？（over-building）
 - 接口是否与规格一致？
 - 测试是否覆盖规格中的验收条件？
+- 如果提出 finding，必须给出复验标准，并在修复后确认原 finding 是否关闭。
 ```
 
 ### 代码质量审查员（Code Quality Reviewer）
@@ -124,8 +138,11 @@ parallel-agent-dispatch
 - 性能考量
 - 安全实践
 - 测试质量
+- 如果提出 finding，必须给出风险等级、期望修复结果和回归结论。
 ```
 
+审查方默认不直接修复。只有用户明确要求“修复 review findings”，或 finding 是机械小修且主线程确认后，才把审查结论转成修复任务。
+
 ## 子代理状态处理
 
 子代理报告四种状态之一：
@@ -151,12 +168,36 @@ parallel-agent-dispatch
 
 | 任务特征 | 推荐审查策略 |
 |---------|------------|
-| 涉及 1-2 个文件，规格明确，机械性实现 | **轻量审查**：仅实现者自审 + 代码质量审查（跳过规格审查子代理） |
-| 涉及多文件，有接口/集成关注点 | **标准审查**：完整三角色（实现者自审 + 规格审查 + 质量审查） |
-| 涉及设计判断或广泛代码库理解 | **加强审查**：完整三角色 + 更强模型 |
+| 涉及 1-2 个文件，规格明确，机械性实现 | **light review**：实现者自审 + 主线程检查 |
+| 涉及多文件，有接口/集成关注点 | **standard review**：实现者自审 + 独立 reviewer + 提出方回归 |
+| 涉及设计判断、广泛代码库理解或高风险路径 | **strict review**：规格审查 + 代码质量审查 + 测试 / 安全 / 性能按风险加入 |
 
 > **经验参考**：superpowers 项目实测发现，充分的实现者自审可替代大部分审查子代理的工作，将单任务审查时间从 ~25min 降至 ~30s，且缺陷捕获率相当。关键在于实现者自审检查清单的严格执行。
 
+默认中等以上任务使用 `standard review`，高风险任务使用 `strict review`。
+
+## Bugfix 与回归闭环
+
+当审查或回归发现 bug：
+
+1. 主线程先判断归属：实现方引入、集成引入、规格不清或外部环境问题。
+2. 实现方引入的问题优先退回实现方修复。
+3. 同一个 finding 两次修不好时，主线程缩小问题后转派给更合适的 agent 或自己接手。
+4. 提出方负责复验原问题；测试代码可以由实现方补，也可以由 test agent 补，但回归结论由提出方给出。
+5. 主线程运行最终集成验证后才能接受。
+
+回归记录必须能回答：
+
+```text
+Regression:
+- finding:
+- producer:
+- fix:
+- reviewer:
+- regression evidence:
+- controller decision:
+```
+
 ## 模型选择指南
 
 用最经济的模型处理每个角色，节省成本提高速度。
@@ -220,9 +261,10 @@ Task 2: 会话管理
 
 ## Red Flags
 
-- 控制器直接动手实现而不分派子代理
+- 已经选择子代理驱动模式后，控制器绕过已分配 worker 直接改同一任务
 - 跳过规格审查直接进入代码质量审查
 - 子代理报告 BLOCKED 后不做改变就重试
 - 所有任务用同一个最强模型（浪费资源）
 - 子代理间共享上下文（违背隔离原则）
 - 没有最终的整体审查就声明完成
+- reviewer 提出 finding 后不负责回归确认

package/vendor/packages/toolkit/src/content/skills/team-orchestration/body.md

@@ -1,126 +1,133 @@
-# Team Orchestration
-
-## 角色定位
-
-使用 `zc team` 把多个 AI CLI worker 运行在 tmux pane 和 git worktree 中，适合需要文件系统级隔离、长时间并行或多 CLI 协作的任务。
-
-这是重型能力。默认先考虑串行执行或 `parallel-agent-dispatch`；只有用户明确要求多 worker / team 模式，且文件边界清楚时才启动。
-
-## 何时使用
-
-使用：
-
-- 多个任务可以分配给不同 worker。
-- 需要独立 worktree 避免写入冲突。
-- 需要不同 CLI 处理不同类型任务。
-- 任务较长，值得承担 fan-in 和清理成本。
-
-不使用：
-
-- 单个简单任务。
-- 任务高度耦合、共享大量上下文。
-- 没有测试或集成验证方式。
-- 只是想“快一点”，但文件所有权不清。
-
-## 快速路径
-
-1. 先用 `zc doctor` 检查环境。
-2. 用 `zc team plan` 做 dry-run，任务必须带 `files=` 边界。
-3. 只有 `canStart=true` 且用户确认后，才运行 `zc team start`。
-4. 用 `zc team status` 和 `zc team log` 监控 worker。
-5. fan-in 前运行 `zc team shutdown <team> --plan` 查看 clean/dirty/ahead/merged 状态。
-6. 明确每个分支去向后再 `zc team shutdown`。
-
-```bash
-zc doctor
-
-zc team plan \
-  -w 2 \
-  -t "API | files=src/api.ts,src/api.test.ts" \
-  -t "UI | files=src/ui.ts,src/ui.test.ts"
-
-zc team start \
-  -w "w1:codex,w2:qwen-code" \
-  -t "API | files=src/api.ts,src/api.test.ts" \
-  -t "UI | files=src/ui.ts,src/ui.test.ts"
-
-zc team status <team-name>
-zc team log <team-name>
-zc team shutdown <team-name> --plan
-zc team shutdown <team-name>
-```
-
-## 任务描述规则
-
-每个 `-t` 至少包含：
-
-- 任务名
-- `files=` 文件或目录所有权
-- 验收标准
-- 验证命令
-
-示例：
-
-```text
-实现用户认证 API | files=src/auth.ts,src/auth.test.ts | verify=pnpm test auth
-```
-
-没有 `files=` 时，默认不能证明任务可安全并行。
-
-## 启动前推荐格式
-
-```text
-Recommendation: 使用 zc team because <文件系统隔离收益> outweighs <tmux/worktree/fan-in 成本>。
-- worker：
-- worktree 边界：
-- 不使用 team 的替代方案：
-- fan-in 验证：
-- 清理策略：
-
-确认后我再启动；不确认则按串行或 Context Fan-Out 推进。
-```
-
-## Worker 协作纪律
-
-- 每个 worker 只修改自己的 `files=` 范围。
-- 共享接口变更必须通过 mailbox 或主线程广播。
-- worker 完成时报告修改文件、验证结果和待集成事项。
-- 主线程负责最终集成，不把 fan-in 交给任意单个 worker 自行处理。
-
-## Fan-In 与收尾
-
-结束前必须记录：
-
-```text
-Team acceptance transcript:
-- Team:
-- Workers:
-- Task ownership:
-- Branch/worktree status:
-- Worker results:
-- Integrated diff:
-- Verification:
-- Cleanup:
-```
-
-收尾判断：
-
-- clean 且已合入：可删除 worktree/branch。
-- dirty：先读 diff，决定合入、保留或放弃。
-- ahead 但未合入：明确是否提交、PR 或丢弃。
-- unknown：不要直接删除，先人工确认状态。
-
-## 边界与安全
-
-- 不把 `zc team` 当成默认实现方式。
-- 不为了形式统一创建多个 worker。
-- 不在未验证 `canStart=true` 时启动。
-- 不直接清理 dirty worktree。
-- 不混入破坏性 git 操作；需要删除或重置时必须先确认。
-
-## 相关技能
-
-- `parallel-agent-dispatch`：上下文级并行，成本更低。
-- `subagent-driven-development`：串行子代理委派。
-- `branch-finish-and-cleanup`：分支和 worktree 收尾。
-- `verification-before-completion`：声明完成前的最终证据门禁。
+# Team Orchestration
+
+## 角色定位
+
+使用 `zc team` 把多个 AI CLI worker 运行在 tmux pane 和 git worktree 中，适合需要文件系统级隔离、长时间并行或多 CLI 协作的任务。
+
+这是重型能力。默认先考虑串行执行或 `parallel-agent-dispatch`；只有用户明确要求多 worker / team 模式，或用户确认 `agent_opportunity.mode=zc-team`，且文件边界清楚时才启动。
+
+## 何时使用
+
+使用：
+
+- 多个任务可以分配给不同 worker。
+- 需要独立 worktree 避免写入冲突。
+- 需要 Codex / Qwen 等不同 CLI 处理不同类型任务。
+- 任务较长，值得承担 fan-in 和清理成本。
+
+不使用：
+
+- 单个简单任务。
+- 任务高度耦合、共享大量上下文。
+- 没有测试或集成验证方式。
+- 只是想“快一点”，但文件所有权不清。
+
+## 快速路径
+
+1. 先用 `zc doctor` 检查环境。
+2. 确认 project-local worktree root 已被忽略；如果没有，把 `.worktrees/` 加入 `.gitignore` 或改用仓库外目录。
+3. 用 `zc team plan` 做 dry-run，任务必须带 `files=` 边界。
+4. 只有 `canStart=true` 且用户确认后，才运行 `zc team start`。
+5. 用 `zc team status` 和 `zc team log` 监控 worker。
+6. fan-in 前运行 `zc team shutdown <team> --plan` 查看 clean/dirty/ahead/merged 状态。
+7. 明确每个分支去向后再 `zc team shutdown`。
+
+```bash
+zc doctor
+
+zc team plan \
+  -w 2 \
+  -t "API | files=src/api.ts,src/api.test.ts" \
+  -t "UI | files=src/ui.ts,src/ui.test.ts"
+
+zc team start \
+  -w "w1:codex,w2:qwen-code" \
+  -t "API | files=src/api.ts,src/api.test.ts" \
+  -t "UI | files=src/ui.ts,src/ui.test.ts"
+
+zc team status <team-name>
+zc team log <team-name>
+zc team shutdown <team-name> --plan
+zc team shutdown <team-name>
+```
+
+## 任务描述规则
+
+每个 `-t` 至少包含：
+
+- 任务名
+- `files=` 文件或目录所有权
+- 验收标准
+- 验证命令
+
+示例：
+
+```text
+实现用户认证 API | files=src/auth.ts,src/auth.test.ts | verify=pnpm test auth
+```
+
+没有 `files=` 时，默认不能证明任务可安全并行。
+
+## 启动前推荐格式
+
+```text
+Recommendation: 使用 zc team because <文件系统隔离收益> outweighs <tmux/worktree/fan-in 成本>。
+- worker：
+- worktree 边界：
+- 不使用 team 的替代方案：
+- fan-in 验证：
+- 清理策略：
+
+确认后我再启动；不确认则按串行或 Context Fan-Out 推进。
+```
+
+即使 `start` 或 `task-plan` 输出 `agent_opportunity.mode=zc-team`，也只能作为建议。没有用户明确确认时，不运行 `zc team start`。
+
+## Worker 协作纪律
+
+- 每个 worker 只修改自己的 `files=` 范围。
+- 共享接口变更必须通过 mailbox 或主线程广播。
+- worker 完成时报告修改文件、验证结果和待集成事项。
+- 主线程负责最终集成，不把 fan-in 交给任意单个 worker 自行处理。
+- review finding 按 `producer owns fix` 和 `reviewer owns regression` 闭环；提出方必须回归确认，主线程负责接受或转派。
+
+## Fan-In 与收尾
+
+结束前必须记录：
+
+```text
+Team acceptance transcript:
+- Team:
+- Workers:
+- Task ownership:
+- Branch/worktree status:
+- Worker results:
+- Findings/fixes/regression:
+- Integrated diff:
+- Verification:
+- Cleanup:
+```
+
+收尾判断：
+
+- clean 且已合入：可删除 worktree/branch。
+- dirty：先读 diff，决定合入、保留或放弃。
+- ahead 但未合入：明确是否提交、PR 或丢弃。
+- unknown：不要直接删除，先人工确认状态。
+
+## 边界与安全
+
+- 不把 `zc team` 当成默认实现方式。
+- 不为了形式统一创建多个 worker。
+- 不在用户未明确确认时启动，即使并行看起来有收益。
+- 不在未验证 `canStart=true` 时启动。
+- 不在项目内创建未被 `.gitignore` 覆盖的 worktree root。
+- 不直接清理 dirty worktree。
+- 不混入破坏性 git 操作；需要删除或重置时必须先确认。
+
+## 相关技能
+
+- `parallel-agent-dispatch`：上下文级并行，成本更低。
+- `subagent-driven-development`：串行子代理委派。
+- `branch-finish-and-cleanup`：分支和 worktree 收尾。
+- `verification-before-completion`：声明完成前的最终证据门禁。

package/vendor/packages/toolkit/src/content/skills/test-driven-development/body.md

@@ -1,78 +1,78 @@
-# 测试驱动开发
-
-## 角色定位
-
-先用测试定义期望行为，再写最小实现让测试通过。这个 skill 负责行为变更的证据闭环，不负责铺满测试理论或替代专项浏览器 QA。
-
-## 何时使用
-
-- 新增或修改可观察行为。
-- 修复 bug，需要先复现再修复。
-- 重构可能影响现有行为。
-- 需要为边界条件、错误路径或兼容性补回归保护。
-
-不适用：纯文档、纯静态内容、无行为影响的配置调整。浏览器体验改动需要再接 `browser-qa-testing`。
-
-## 快速路径
-
-1. 写清要证明的行为或 bug 症状。
-2. 选择最小测试层级：unit / integration / E2E。
-3. **RED**：先写一个会失败的测试，确认失败原因匹配目标。
-4. **GREEN**：写最小实现，只让当前测试通过。
-5. **REFACTOR**：在测试保持绿色的前提下简化实现。
-6. 跑相关回归测试，确认没有破坏邻近行为。
-7. 记录测试证据和仍未覆盖的风险。
-
-## Bug 修复 Prove-It 模式
-
-```text
-Bug report -> Reproduction test fails -> Fix -> Reproduction test passes -> Regression suite passes
-```
-
-如果无法先写复现测试，必须说明原因，并给出替代证据，例如最小命令、日志、浏览器 transcript 或人工可复查步骤。
-
-## 测试层级选择
-
-| 层级 | 何时选 | 代价 |
-|---|---|---|
-| Unit | 纯逻辑、边界判断、数据转换 | 快，信心局部 |
-| Integration | API、数据库、文件系统、模块边界 | 中等，能发现契约问题 |
-| E2E / Browser | 用户关键路径、前端集成体验 | 慢，但最接近真实用户 |
-
-默认从能证明目标的最低成本层级开始。不要为了形式写高层测试，也不要用过度 mock 让测试只证明实现细节。
-
-## 测试质量门禁
-
-- 测试名字描述行为，而不是实现细节。
-- 断言结果状态，少断言内部调用顺序。
-- 测试数据最小且可读，优先 DAMP 而不是过度 DRY。
-- mock 只用于慢、不可控或有副作用的外部依赖。
-- 每个测试失败时应指向一个清晰原因。
-
-## 反模式
-
-- 先写实现，再补一个永远会过的测试。
-- 修改测试来迁就错误实现。
-- 跳过失败测试继续加功能。
-- 用快照覆盖大量不稳定 UI，导致 diff 不可审。
-- 为了覆盖率写不验证业务行为的测试。
-
-## 输出契约
-
-```text
-TDD evidence:
-- Behavior:
-- Test added/changed:
-- Red result:
-- Green result:
-- Regression command:
-- Remaining risk:
-```
-
-推荐结论使用：
-
-```text
-Recommendation: <继续实现 / 修复测试 / 补更高层验证 / 进入 review> because <测试证据、风险和被放弃替代方案>。
-```
-
-没有读过失败输出和通过输出，不要声明测试闭环成立。
+# 测试驱动开发
+
+## 角色定位
+
+先用测试定义期望行为，再写最小实现让测试通过。这个 skill 负责行为变更的证据闭环，不负责铺满测试理论或替代专项浏览器 QA。
+
+## 何时使用
+
+- 新增或修改可观察行为。
+- 修复 bug，需要先复现再修复。
+- 重构可能影响现有行为。
+- 需要为边界条件、错误路径或兼容性补回归保护。
+
+不适用：纯文档、纯静态内容、无行为影响的配置调整。浏览器体验改动需要再接 `browser-qa-testing`。
+
+## 快速路径
+
+1. 写清要证明的行为或 bug 症状。
+2. 选择最小测试层级：unit / integration / E2E。
+3. **RED**：先写一个会失败的测试，确认失败原因匹配目标。
+4. **GREEN**：写最小实现，只让当前测试通过。
+5. **REFACTOR**：在测试保持绿色的前提下简化实现。
+6. 跑相关回归测试，确认没有破坏邻近行为。
+7. 记录测试证据和仍未覆盖的风险。
+
+## Bug 修复 Prove-It 模式
+
+```text
+Bug report -> Reproduction test fails -> Fix -> Reproduction test passes -> Regression suite passes
+```
+
+如果无法先写复现测试，必须说明原因，并给出替代证据，例如最小命令、日志、浏览器 transcript 或人工可复查步骤。
+
+## 测试层级选择
+
+| 层级 | 何时选 | 代价 |
+|---|---|---|
+| Unit | 纯逻辑、边界判断、数据转换 | 快，信心局部 |
+| Integration | API、数据库、文件系统、模块边界 | 中等，能发现契约问题 |
+| E2E / Browser | 用户关键路径、前端集成体验 | 慢，但最接近真实用户 |
+
+默认从能证明目标的最低成本层级开始。不要为了形式写高层测试，也不要用过度 mock 让测试只证明实现细节。
+
+## 测试质量门禁
+
+- 测试名字描述行为，而不是实现细节。
+- 断言结果状态，少断言内部调用顺序。
+- 测试数据最小且可读，优先 DAMP 而不是过度 DRY。
+- mock 只用于慢、不可控或有副作用的外部依赖。
+- 每个测试失败时应指向一个清晰原因。
+
+## 反模式
+
+- 先写实现，再补一个永远会过的测试。
+- 修改测试来迁就错误实现。
+- 跳过失败测试继续加功能。
+- 用快照覆盖大量不稳定 UI，导致 diff 不可审。
+- 为了覆盖率写不验证业务行为的测试。
+
+## 输出契约
+
+```text
+TDD evidence:
+- Behavior:
+- Test added/changed:
+- Red result:
+- Green result:
+- Regression command:
+- Remaining risk:
+```
+
+推荐结论使用：
+
+```text
+Recommendation: <继续实现 / 修复测试 / 补更高层验证 / 进入 review> because <测试证据、风险和被放弃替代方案>。
+```
+
+没有读过失败输出和通过输出，不要声明测试闭环成立。