@captain_z/zsk-skills 1.2.0 → 1.3.0

package/sdlc/task-evidence/SKILL.md

@@ -9,9 +9,12 @@ category: resource
 domain: sdlc
 tier: core
 related:
+  - ../../system/agent-orchestration/SKILL.md
   - ../task/SKILL.md
   - ../task-structure/SKILL.md
+  - ../task-tracking/SKILL.md
   - ../verify/SKILL.md
+  - ../../design-handoff/ue-mcp/SKILL.md
   - ../../frontend/nfr-web/SKILL.md
 triggers:
   - FR coverage matrix
@@ -120,6 +123,26 @@ triggers:
 
 > 前端项目额外：视觉回归 / a11y / i18n / 性能（Lighthouse）/ 包体积（Bundle Analyzer）— 见 [`zsk:nfr-web`](../../frontend/nfr-web/SKILL.md)
 
+### 批次验证记录
+
+每个可审计批次完成时必须追加一行：
+
+```md
+## 批次验证记录
+
+| 批次 | 覆盖 FR/AC | 自动验证 | 结果 | 证据 |
+| --- | --- | --- | --- | --- |
+| B-1 | FR-1, AC-1 | unit + type-check + lint | ✅ | {报告链接} |
+| B-2 | FR-2, AC-3 | Figma MCP + Computer Use + a11y | ✅ | {ue-mcp / 截图 / 录屏} |
+```
+
+前端高保真批次的证据至少包含：
+
+- Figma URL / node-id / `ue-mcp.md` 快照
+- Computer Use 或等价浏览器流验证
+- 关键状态截图：default / loading / empty / error / focus-visible
+- 视觉差异或人工差异记录
+
 ### 门禁类别（按变更类型）
 
 | 类别 | Feature | Bugfix | Refactor |

package/sdlc/task-structure/SKILL.md

@@ -9,6 +9,7 @@ category: resource
 domain: sdlc
 tier: core
 related:
+  - ../../system/agent-orchestration/SKILL.md
   - ../task/SKILL.md
   - ../task-tracking/SKILL.md
   - ../task-evidence/SKILL.md

package/sdlc/task-tracking/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: zsk:task-tracking
 description: Task execution tracking — dependencies (Mermaid graph), blockers
-  (dated log with severity H/M/L and escalation rules), milestones (stage exits
-  with committed dates), and task state transitions (TODO → DOING → DONE, with
+  (dated log with severity H/M/L and escalation rules), milestones, auditable
+  LLM execution batches, and task state transitions (TODO → DOING → DONE, with
   BLOCKED requiring log entry).
 category: resource
 domain: sdlc
@@ -10,7 +10,9 @@ tier: core
 related:
   - ../task/SKILL.md
   - ../task-structure/SKILL.md
+  - ../task-evidence/SKILL.md
   - ../dor-dod/SKILL.md
+  - ../../system/agent-orchestration/SKILL.md
 triggers:
   - task dependency graph
   - blocker log
@@ -141,35 +143,55 @@ tasks.md 可选的 daily 汇报 section：
 2. **明天要推进哪些**？
 3. **有什么阻塞、谁能解**？
 
-## 6. 每任务交互契约（LLM / 代理执行）
+## 6. 可审计批次交互契约（LLM / 代理执行）
 
-当任务由 LLM 或代理执行时，**单任务完成的交互流程**必须遵守，不自动连跑：
+当任务由 LLM 或代理执行时，默认按**可审计批次**推进，而不是机械地每个小任务都停。批次完成后自动验证、自动记录证据；只在风险门禁处停。批次可以是：
+
+- `tasks.md` 中显式声明的任务组
+- 一个完整 FR 切片
+- 一个风险闭环（如 Red → Green → Regression）
+- 一组只读扫描 / 调研任务
+- 用户显式授权的任务组（如"跑完 T-1/T-2/T-3 再一起确认"）
+
+若 `tasks.md` 没有任务组，默认把**全部任务视为一个任务组**；只有用户指定“哪些任务完成后再统一验证”时，才按用户指定分组覆盖默认。
+
+批次完成后必须停在 checkpoint：
 
 ```text
-执行任务
+执行批次
    ↓
-更新状态（DOING → DONE）+ 填证据链接
+自动运行批次验证（测试 / Figma MCP / Computer Use / Review 自查等按范围选择）
    ↓
-短汇报（1-3 句："做了什么 + 证据位置"）
+更新状态（DOING → DONE）+ 填证据链接 + 标记覆盖 FR/AC
    ↓
-等待人类确认 ← 停在这里，不自动推进下一个
+短汇报（1-3 句："做了什么 + 证据位置 + 下一批建议"）
+   ↓
+等待人类确认 / 或触发任务组 Reviewing ← 停在这里，不自动跨阶段
    ↓
 人类决策：
-   ├─ 通过     → 推进下一任务
+   ├─ 通过     → 推进下一批次
    ├─ 需修改   → 状态回 DOING + 追加子任务
    └─ 范围变动 → 回 spec/design 走变更流程
 ```
 
-### 何时可例外
+### 必须在当前任务停下的情况
+
+- 新增依赖 / 改公共 API / 改权限或数据一致性路径
+- 测试无法运行、证据缺失、或需要用户豁免
+- 出现 Spec / Design 冲突
+- 单轮改动超过项目阈值，或达到 `standard-dev-flow` 的 Review 触发条件
+- Figma MCP / Computer Use 等关键验收工具不可用且没有等价替代证据
+
+### 可连续推进的情况
 
-- **纯读取任务**（调研、搜索、只读扫描）可批量推进不等确认
-- **用户显式授权"连跑 N 个"**（如 "跑完 T-1/T-2/T-3 再一起确认"）
+- **纯读取任务**（调研、搜索、只读扫描）
+- **用户显式授权"连跑 N 个"**
 - **CI/CD 内的自动化任务**（独立兜底 + PR review 兜底）
 
 ### 为什么
 
-- **证据先于断言**：每步落证据 + 人类审计，防止错误级联
-- **决策归属**：LLM 执行、人类决策——每任务一个 checkpoint
+- **证据先于断言**：每个批次自动验证 + 落证据，防止错误级联
+- **决策归属**：LLM 执行、人类决策——每个任务组 / 批次一个 checkpoint
 - **上下文友好**：刚做完时状态最清晰，拖到批末补证据找不回上下文
 - **映射 GSD**：每个 Engage 后回 Reflect，不是无休止 Engage
 
@@ -188,5 +210,5 @@ DoR / DoD 检出问题时：
 - ❌ 里程碑一直滑动但不写解释（信任损耗）
 - ❌ `DONE` 后偷改（审计无据）
 - ❌ 一个人同时 `DOING` 3+ 任务（上下文切换毒药）
-- ❌ LLM / 代理自动连跑多任务不停（失去人类审计点；见 §6）
+- ❌ LLM / 代理自动跨批次或跨阶段不停（失去人类审计点；见 §6）
 - ❌ 状态更新延迟到批末（刚做完是最佳落证据窗口）

package/sdlc/verify/SKILL.md

@@ -16,6 +16,7 @@ related:
   - ../archive/SKILL.md
   - ../dor-dod/SKILL.md
   - ../task-evidence/SKILL.md
+  - ../../system/agent-orchestration/SKILL.md
   - ../../system/nfr-baseline/SKILL.md
   - ../../frontend/nfr-web/SKILL.md
 triggers:
@@ -32,6 +33,7 @@ triggers:
 > **阶段定位**：验收 / Acceptance Verification
 > **回答的问题**：交付物是否满足 Spec 约定，且有可复验的证据支撑
 > **与 Reviewing 的边界**：Reviewing 看代码和 diff；Verify 看契约和结果。两者互补，不能互相替代。
+> **多 Agent 协议**：复杂验收按 [`zsk:agent-orchestration`](../../system/agent-orchestration/SKILL.md) 分配 Verifier / Design Reviewer / Security Reviewer 等角色，主 Agent 复核最终结论。
 
 ## 核心原则
 

package/system/adr/SKILL.md

@@ -8,6 +8,7 @@ category: resource
 domain: system
 tier: optional
 related:
+  - ../agent-orchestration/SKILL.md
   - ../architecture/SKILL.md
   - ../../sdlc/design/SKILL.md
   - ../../sdlc/archive/SKILL.md

package/system/agent-orchestration/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: zsk:agent-orchestration
+description: Agent orchestration protocol for all zsk skills — assigns
+  independent work to specialized Sub-Agents, defines main-agent ownership, role
+  boundaries, review integration, and fallback behavior when delegation is
+  unavailable.
+category: resource
+domain: system
+tier: core
+related:
+  - ../../meta/philosophy/SKILL.md
+  - ../../sdlc/standard-dev-flow/SKILL.md
+  - ../../sdlc/coding/SKILL.md
+  - ../../sdlc/reviewing/SKILL.md
+  - ../../sdlc/task-tracking/SKILL.md
+triggers:
+  - sub agent orchestration
+  - parallel agents
+  - multi agent workflow
+  - agent responsibilities
+  - delegate tasks
+  - 各司其职
+---
+
+# Agent Orchestration · 多 Agent 协作协议
+
+> **适用范围**：所有 zsk skills。只要任务可拆成独立问题域，默认由主 Agent 制定分工，Sub-Agent 各司其职。
+> **核心原则**：主 Agent 对最终结果负责；Sub-Agent 只负责专业视角或明确文件范围，不直接放行。
+
+## 角色边界
+
+| 角色 | 职责 | 禁止 |
+| --- | --- | --- |
+| 主 Agent | 理解用户目标、拆分任务、分配 Sub-Agent、整合结论、做最终判断 | 把 Sub-Agent 结论原样当事实；放弃最终责任 |
+| Explorer | 只读调研、代码/文档扫描、风险定位、提出证据 | 修改文件；给最终放行 |
+| Worker | 在指定文件 / 模块范围内实现或修复 | 修改未授权范围；回滚他人改动 |
+| Reviewer | 独立审查业务完成度、正确性、测试、前端体验、安全等视角 | 直接改代码；替主 Agent 决策 |
+| Verifier | 跑验证、核对证据、复查 AC / NFR | 用未运行的检查声称通过 |
+
+## 自动分配规则
+
+满足任一条件时，主 Agent 应自动制定 Sub-Agent Assignment Plan：
+
+- 任务跨 2 个以上独立领域（如前端 + API 契约 + 测试）
+- diff 或计划跨 5 个以上文件
+- 涉及安全、权限、资金、数据一致性、公共 API、迁移、性能关键路径
+- 需要同时覆盖产品/设计、工程、测试、风险、发布等不同视角
+- 用户明确要求 sub-agent / parallel agents / 各司其职
+
+如果平台或用户策略不允许实际派发 Sub-Agent，主 Agent 必须按同样角色顺序自查，并在输出中写明“降级为单 Agent 执行”。
+
+## 自动流水线职责
+
+一旦进入 zsk 工作流，主 Agent 不需要等待用户逐个点名 skill。主 Agent 应自动选择下一步相关 skill 和 Sub-Agent：
+
+| 阶段/批次 | 默认分工 |
+| --- | --- |
+| Proposal / Spec | Explorer 收集事实源；Reviewer 查范围和可测试性 |
+| Design | Explorer 扫现状；Reviewer 查架构/设计风险；前端任务补 Design Reviewer |
+| Coding | Worker 按文件范围实现；Verifier 跑批次验证；Reviewer 做轻量自查 |
+| UI / 高保真 | Design Reviewer 对照 Figma MCP；Verifier 用 Computer Use 走用户流 |
+| Reviewing | 多 Reviewer 按业务、风险、测试、前端、安全分视角 |
+| Verify | Verifier 核 AC/NFR 证据；主 Agent 输出最终结论 |
+
+自动化停止点只有：阶段门禁、Review 红灯、Verify 失败、范围变化、工具缺失需豁免、或用户明确暂停。
+
+## 分配计划模板
+
+```md
+## Sub-Agent Assignment Plan
+
+| Agent | 类型 | 责任范围 | 输入 | 输出 | 写权限 |
+| --- | --- | --- | --- | --- | --- |
+| A1 | Explorer | 现状扫描 / 风险定位 | spec, design, paths | 证据清单 | 无 |
+| A2 | Worker | {文件/模块} 实现 | tasks, design | 修改摘要 | {明确路径} |
+| A3 | Reviewer | 测试 / 安全 / 前端体验 | diff, evidence | findings | 无 |
+```
+
+## 拆分纪律
+
+- **按问题域拆**：业务完成度、数据流、前端体验、测试、安全、发布可分开。
+- **按写范围拆**：Worker 必须有明确文件 / 模块所有权。
+- **不拆阻塞任务**：主 Agent 下一步立即依赖的关键判断，优先本地处理。
+- **不重复劳动**：多个 Sub-Agent 不扫描同一问题域，除非是独立复核。
+- **输入自包含**：每个 Sub-Agent 拿到目标、范围、关键文件、输出格式和禁止事项。
+- **输出可整合**：必须包含证据、路径、置信度、风险和建议动作。
+
+## 写权限规则
+
+多个 Worker 并行时必须显式声明：
+
+- 每个 Worker 的 owned files / modules
+- 其他人也在代码库工作，不得回滚未知改动
+- 遇到共享文件冲突时停止并回报主 Agent
+- 生成代码后列出修改路径和验证结果
+
+## Review / Verify 角色
+
+Review 和 Verify 默认适合多 Agent：
+
+- Business / Completion：是否实现 Spec
+- Correctness / Risk：状态机、边界、并发、权限
+- Test / TDD：Red-Green、覆盖矩阵、缺口
+- Frontend / Design：视觉、交互、a11y、响应式、反 AI 化
+- Security / Contract：API、数据、依赖、安全红线
+
+主 Agent 必须复核 Important/Critical 结论，合并重复 findings，并按严重性输出最终判定。
+
+## 质量门禁
+
+- [ ] 已判断是否需要 Sub-Agent Assignment Plan
+- [ ] 每个 Sub-Agent 职责单一、输入自包含、输出格式明确
+- [ ] Worker 写权限不重叠或冲突可控
+- [ ] 主 Agent 已复核高风险结论
+- [ ] 不可派发时已按同角色降级自查并记录原因

package/system/architecture/SKILL.md

@@ -8,6 +8,7 @@ category: resource
 domain: system
 tier: optional
 related:
+  - ../agent-orchestration/SKILL.md
   - ../adr/SKILL.md
   - ../../sdlc/design/SKILL.md
 triggers:

package/system/glossary/SKILL.md

@@ -8,6 +8,7 @@ category: resource
 domain: system
 tier: optional
 related:
+  - ../agent-orchestration/SKILL.md
   - ../../sdlc/spec/SKILL.md
 triggers:
   - glossary

package/system/nfr-baseline/SKILL.md

@@ -9,6 +9,7 @@ category: resource
 domain: system
 tier: optional
 related:
+  - ../agent-orchestration/SKILL.md
   - ../adr/SKILL.md
   - ../../frontend/nfr-web/SKILL.md
   - ../../sdlc/spec/SKILL.md

package/system/project-constraints-template/SKILL.md

@@ -9,6 +9,7 @@ category: resource
 domain: system
 tier: optional
 related:
+  - ../agent-orchestration/SKILL.md
   - ../adr/SKILL.md
   - ../nfr-baseline/SKILL.md
   - ../../meta/philosophy/SKILL.md