@zmice/zc 0.2.5 → 0.2.7

package/vendor/packages/toolkit/src/content/commands/plan-review/body.md

@@ -6,17 +6,19 @@
 
 1. 读取当前 Spec 或 Plan，提取关键决策点
 2. **产品视角**：用户价值清晰？边界覆盖？验收可测？
-3. **工程视角**：方案可行？扩展性和技术债务可控？
+3. **工程视角**：架构、数据流、边界条件、失败模式、测试策略和性能预算可控？
 4. **设计视角**：体验流畅？异常状态完整？一致性足够？
 5. **DevEx 视角**：接口直觉？文档充分？配置合理？
 6. 汇总发现，按 `Critical / Warning / Suggestion` 分级
 7. 存在 `Critical` 时阻断，先修复再继续
+8. 把评审结论写成 plan 可吸收的修订项、验收标准或验证门禁
 
 ## 当前阶段的边界
 
 - 这里只做评审，不直接进入实现
 - 重点是提前暴露盲点，而不是重写整份规格
 - 评审结论必须指向明确修正动作
+- 问题要少而关键；只有会改变方案的疑问才向用户提出
 
 ## 从这里通常接到哪里
 

package/vendor/packages/toolkit/src/content/commands/start/body.md

@@ -8,6 +8,20 @@
 4. 判断风险等级：`trivial` / `standard` / `high-risk`
 5. 输出推荐 workflow、该 workflow 的默认入口和必要的防护建议
 
+## 输出契约
+
+`start` 每次都要给出一个可执行分诊结果，而不是泛泛建议：
+
+- `workflow`：六条固定 workflow 之一
+- `entry`：下一步应该调用的 command / skill，必须是实际可执行入口
+- `agent`：可选协作角色；只有平台支持且用户授权时才建议，不作为默认入口
+- `reason`：用 1-3 条证据说明为什么这样判型
+- `assumption`：如果有未确认前提，明确写出
+- `question`：只有无法安全推进时才问，最多 1-3 个关键问题
+- `verification`：说明完成前需要什么证据
+
+如果信息足够，直接选择保守 workflow 并继续推进；不要为了形式完整而反复提问。
+
 ## 固定 workflow
 
 ### 1. `product-analysis`
@@ -95,12 +109,30 @@
 - 重点是文档、ADR、发布与同步：进入 `docs-release`
 - 当前先要理解项目、修复上下文、摸清约束：进入 `investigation`
 
+### 判型优先级
+
+当一个请求同时命中多个 workflow，按下面顺序消歧：
+
+1. **显式 review findings**：进入 `review-closure`。如果用户要求修复，入口是 `review-response-and-resolution`；如果要求审查所有变更，入口是 `quality-review`。
+2. **CI 失败 / 报错日志 / 可复现异常**：进入 `bugfix`。
+3. **上游更新、依赖升级、陌生能力吸收**：先 `investigation` 拿证据，再按范围进入 `docs-release` 或 `full-delivery`。不能先凭记忆同步。
+4. **文档误导、安装说明 drift、发布后同步**：如果只改文档，进入 `docs-release`；如果文档暴露实现不一致，先 `bugfix`。
+5. **新功能或跨模块优化**：目标和验收明确时进入 `full-delivery`；目标不稳定时先 `product-analysis`。
+6. **生产、数据、破坏性命令、凭据、跨会话记忆或项目路由写入**：主 workflow 不变，但必须加 `guard` / `careful` / `freeze` 这类防护建议。
+
+### 提问纪律
+
+- 能从仓库、日志、diff、配置或用户原话判断的，不问。
+- 只有架构方向、数据安全、破坏性操作、缺失关键上下文、或用户目标互相冲突时才问。
+- 问题要以结果和风险表述：这个选择会避免什么风险、解锁什么能力、改变什么体验。
+- 如果用户已经给出偏好，按偏好执行；偏好不能变成自动写入长期配置或跨会话记忆的授权。
+
 ## 在 workflow 内部的切入点
 
 - `product-analysis`
   - 主入口：`product-analysis`
   - 需要先发散想法：`idea`
-  - 需要产品判断：`product-owner`
+  - 需要产品判断：继续 `product-analysis`；必要时建议 `product-owner` 作为可选 agent
   - 需要方案探索：`brainstorming-and-design`
   - 需要沉淀规格：`spec`
   - 需要做方案评审：`plan-review`
@@ -114,6 +146,7 @@
   - 主入口：`debug`
 - `review-closure`
   - 主入口：`quality-review`
+  - 已有 review findings 且需要修复：`review-response-and-resolution`
 - `docs-release`
   - 文档优先：`doc`
   - 发布优先：`ship`
@@ -122,11 +155,27 @@
   - 上下文漂移：`ctx-health`
   - 需要重新收敛问题：`idea`
 
+## 并行与 agent 判断
+
+`start` 可以评估是否适合并行，但不能把并行当默认：
+
+- 任务能按文件、模块或证据问题拆开，且没有强依赖：可以建议 `parallel-agent-dispatch` 或 `zc team plan`
+- 无法证明独立、存在同文件冲突、存在依赖链：默认串行或先计划
+- 用户没有明确授权时，不自动启动子代理或 `zc team start`
+- 如果进入 `zc team`，先 dry-run：`zc team plan ... --json`
+
+## 上下文与持久化边界
+
+- skill 和 workflow 应按需加载；不要把所有 skill 都常驻上下文
+- `AGENTS.md`、`GEMINI.md`、平台规则文件只放长期项目约定和稳定路由
+- 写入用户级配置、跨项目路由、跨会话记忆或跨机器同步前，必须明确说明影响并取得用户授权
+- 平台不支持的能力不能通过文案暗示支持；例如某个平台没有 native plugin，就走 install / filesystem 适配路线
+
 ## 平台说明
 
 - `start` 是 canonical command，不等于所有平台都有原生同名命令
 - 在 Codex 上，它更适合作为“统一任务开始方式”的自然语言入口
-- 在 Qwen / Qoder 上，可以呈现为更接近命令式的入口文案
+- 在 Qwen / Claude / OpenCode 上，可以呈现为更接近命令式的入口文案
 - 当前阶段没有 `zc start` CLI
 
 ## 使用方式

package/vendor/packages/toolkit/src/content/commands/start/meta.yaml

@@ -1,7 +1,7 @@
 kind: command
 name: start
 title: 开始
-description: 统一任务开始入口，先评估任务，再在 6 条固定 workflow 中选择合适的路线和默认入口。
+description: 统一任务开始入口。用于先评估任务类型、清晰度、阶段与风险，再在 6 条固定 workflow 中选择默认入口；适用于不确定该先分析、实现、调试、审查、补文档还是调查摸底的请求。
 tier: core
 audience: default
 stability: stable
@@ -52,4 +52,4 @@ platform_exposure:
 source:
   upstream: toolkit-original
   strategy: curated
-  notes: 本仓库新增的统一任务入口，用于 intake、任务判型，并在 product-analysis、full-delivery、bugfix、review-closure、docs-release、investigation 六条固定 workflow 中选路；其中 product-analysis 由独立 workflow-entry 承接。
+  notes: 本仓库新增的统一任务入口，用于 intake、任务判型，并在 product-analysis、full-delivery、bugfix、review-closure、docs-release、investigation 六条固定 workflow 中选路；其中 product-analysis 由独立 workflow-entry 承接。2026-04-29 根据 agent-skills 的 trigger/description 经验和 gstack 的 outcome-framed question / stop-gate 经验补强路由纪律。

package/vendor/packages/toolkit/src/content/skills/branch-finish-and-cleanup/body.md

@@ -130,11 +130,28 @@ worktree 是隔离手段，不是长期存档机制。
 
 如果一个并行批次完成后还残留大量无主分支，说明收尾协议没有真正执行。
 
+使用 `zc team` 时，先运行 dry-run：
+
+```bash
+zc team shutdown <team-name> --plan
+```
+
+它只读取 fan-in 状态，不关闭 tmux、不删除 worktree。重点看每个 worker worktree：
+
+- `clean`：没有未提交变更，可以继续判断是否合入或删除
+- `dirty`：仍有未提交变更，必须先转移、提交或明确丢弃
+- `ahead`：分支领先目标引用，需要判断是否合入或开 PR
+- `merged`：已合入的分支可以进入删除流程
+- `unknown`：状态无法判断，必须人工检查后再清理
+
+只有每个 worktree 的去向明确后，才运行不带 `--plan` 的 `zc team shutdown <team-name>`。
+
 ## 最小收尾清单
 
 - [ ] branch 的最终去向已明确
 - [ ] 必要验证已完成，证据可追溯
 - [ ] 需要保留的信息已转移到 PR、任务系统或文档
+- [ ] `zc team shutdown <team-name> --plan` 没有暴露未解释的 `dirty` / `unknown`
 - [ ] 不再需要的 branch 已删除
 - [ ] 不再需要的 worktree 已移除
 - [ ] 没有遗留未解释的脏文件或临时产物