@aipper/aiws-spec 0.0.24 → 0.0.25

package/docs/workflow-stage-contracts.md

@@ -0,0 +1,70 @@
+# workflow-stage-contracts
+
+<!-- Generated from packages/spec/docs/workflow-stage-contracts.json by scripts/sync-workflow-stage-contracts.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档把 `aiws` 核心 `ws-*` workflow 的阶段契约写成统一真值，避免不同工具、不同协作者把同一个入口用成不同语义。
+
+重点不是“命令名长什么样”，而是每个阶段必须收什么输入、产出什么结果、在什么情况下必须停止。
+
+## 标准链路
+
+默认链路：
+
+`ws-preflight` -> `ws-plan` -> `ws-plan-verify` -> `ws-dev` -> `ws-review` -> `ws-commit` -> `ws-deliver` -> `ws-finish` -> `ws-handoff`
+
+说明：
+- ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。
+- ws-finish 用于 fast-forward 合并、push 和 worktree cleanup。
+- ws-handoff 通常在 archive 后使用，为下一次会话留下交接说明。
+- 若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。
+
+## 阶段表
+
+| Stage | 目标 | 必需输入 | 必需输出 | 阻断条件 | 下一步 |
+| --- | --- | --- | --- | --- | --- |
+| `ws-preflight` | 对齐真值文件与协作约束 | 项目根；AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md | Root / Found / Missing / Key rules / Next | 无法确定项目根；真值缺失 | ws-plan 或 ws-dev |
+| `ws-plan` | 建立 change 绑定并落盘计划 | 任务描述；真值文件；proposal.md（若存在） | plan/...；Bindings；Verify；Risks；Evidence；Next | 绑定不清；dirty 工作区无法安全建 context；无法写盘 | ws-plan-verify |
+| `ws-plan-verify` | 检查计划是否满足严格契约 | plan/...；proposal.md；当前 change | Quality gate；Fix list；可执行最小计划摘要 | strict 校验失败；无法定位 change | 修计划后重跑或进入 ws-dev |
+| `ws-dev` | 实施最小改动并验证 | 真值文件；归因目标；计划（medium/complex） | Changed；Verify；Evidence；Next | 无法归因；没有验证入口；change 上下文不安全 | ws-review / ws-commit |
+| `ws-review` | 审计规范、风险与验证完整性 | 当前 diff；验证结果；真值文件 | review 文件；Top risks；Next | 无改动可审；无法写审计证据 | ws-commit 或修复后重审 |
+| `ws-commit` | 串联 review、validate、commit 确认 | staged diff；review 证据；validate stamp；用户确认的 message | Evidence；Context；Commit | 无 staged changes；submodule dirty；validate 失败；message 未确认 | ws-deliver / ws-finish |
+| `ws-deliver` | 在 submodule 场景下完成顺序提交与证据收敛 | change 上下文；.gitmodules；submodules.targets；各 repo 状态 | submodule 提交摘要；superproject 提交摘要；Evidence | submodule 真值不完整；不在正确 change；commit 未确认 | ws-finish |
+| `ws-finish` | 安全合并、push、cleanup | 干净工作区；已提交的 change；push 目标；submodule 真值（若有） | Merge；Push；Worktree cleanup；Evidence | dirty 工作区；ff 失败；submodule 无法安全 push | ws-handoff 或 archive |
+| `ws-handoff` | 生成可接力的归档交接说明 | 已归档或待归档的 change | changes/archive/.../handoff.md；Next | 无法定位 change；archive 失败；handoff 无法生成 | 新 change 通过 Depends_On 接力 |
+
+## 统一规则
+
+- 每个阶段都必须回指真值文件或 change 工件，不能只依赖会话上下文。
+- 每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。
+- 遇到阻断条件时必须停止，不能为了推进速度跳过门禁。
+- 如果一个阶段没有留下可审计路径，它就不算真正完成。
+- `ws-finish` 只有在 merge、push、cleanup 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。
+
+## 证据约定
+
+最少证据集合：
+
+- planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
+- review：`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`
+- validate：`.agentdocs/tmp/aiws-validate/*.json`
+- deliver / finish：`changes/<change-id>/evidence/...`、`state`、merge / push 结果
+- handoff：`changes/archive/.../handoff.md`
+
+补充：
+- tmp review 证据可以作为“进入 commit gate”的临时治理信号，但在交付前应通过 `aiws change evidence` 收敛为持久 review 证据。
+- finish 生命周期建议区分“本地开始”和“完整完成”两类信号，避免仅凭本地 merge 就误导到 handoff。
+
+## 与产品定位的关系
+
+这份阶段契约文档是 `aiws` “治理内核”定位的直接落点：
+
+- `packages/spec/` 继续作为规则真值层
+- `ws-*` 阶段契约是工作流治理层
+- `docs/workflow-stage-contracts.json` 是运行时阶段契约的机器可读真值
+- `docs/workflow-governance-rules.json` 是运行时阶段推断的机器可读真值
+- CLI / tool-native files 是执行与分发层
+- review / validate / handoff 等工件属于证据与审计层
+
+如果未来要吸收新的 skill、协同角色或外部 workflow，优先判断它能否被映射到这张阶段表；不能稳定映射的能力，不应直接成为核心真值。

package/docs/workflow-stage-contracts.schema.json

@@ -0,0 +1,98 @@
+{
+  "type": "object",
+  "required": [
+    "version",
+    "title",
+    "description",
+    "purpose",
+    "standardChain",
+    "notes",
+    "stages",
+    "unifiedRules",
+    "evidence",
+    "positioning"
+  ],
+  "properties": {
+    "version": { "type": "integer" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "purpose": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "standardChain": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" }
+    },
+    "notes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["stage", "goal", "requiredInputs", "requiredOutputs", "blockers", "next"],
+        "properties": {
+          "stage": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" },
+          "goal": { "type": "string", "minLength": 1 },
+          "requiredInputs": { "type": "string", "minLength": 1 },
+          "requiredOutputs": { "type": "string", "minLength": 1 },
+          "blockers": { "type": "string", "minLength": 1 },
+          "next": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "unifiedRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["intro", "minimum", "notes"],
+      "properties": {
+        "intro": { "type": "string", "minLength": 1 },
+        "minimum": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["label", "value"],
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "value": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          }
+        },
+        "notes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "positioning": {
+      "type": "object",
+      "required": ["intro", "layers", "closing"],
+      "properties": {
+        "intro": { "type": "string", "minLength": 1 },
+        "layers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "closing": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.agents/skills/using-aiws/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: using-aiws
+description: 默认 workflow bootstrap/router：先读真值，再路由到正确的 ws-* 入口
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
+- 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+
+阶段定位：
+- bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
+
+必需输入：
+- 当前任务描述
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Task intent:` 当前任务意图分类
+- `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
+- `Route:` 选中的下一步 skill
+- `Why:` 选择该 route 的原因
+- `Next:` 进入对应 skill，或先提澄清问题
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+- 无法明确当前任务意图
+- 无法明确归因或验证入口，且不能安全推断
+
+完成判定：
+- 已经明确给出单一路由结果，并进入对应 `ws-*` skill；或已提出关键澄清问题并停止。
+
+执行步骤（强制）：
+1) 先遵守 `$ws-preflight` 的真值读取要求：
+   - 定位项目根目录
+   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+   - 输出 `Root:` / `Found:` / `Missing:`
+2) 若缺失任一真值文件：
+   - 不进入实现
+   - 输出下一步：先 `aiws init .`（或 `npx @aipper/aiws init .`），然后重新执行 `$using-aiws`
+   - 此时 route 视为 `$ws-preflight`
+3) 根据 `packages/spec/docs/workflow-router-rules.json` 判定任务属于哪一类：
+   - 需求/验收/合同变更：`$ws-req-review`
+   - 评审/审计/找风险：`$ws-review`
+   - finish / merge / push / cleanup：`$ws-finish`
+   - handoff / archive summary：`$ws-handoff`
+   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
+   - 小步明确实现/修复/配置调整：`$ws-dev`
+4) 若任务意图或归因不明确：
+   - 只问 1-3 个关键澄清问题
+   - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
+   - 然后停止；不要直接写代码
+5) 若已确定 route：
+   - 先输出：
+     - `Task intent:`
+     - `Binding:`
+     - `Route:`
+     - `Why:`
+   - 然后在同一轮中继续遵循对应 skill 的契约
+6) 路由约束：
+   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+7) 若执行过程中发现复杂度升高：
+   - 从 `$ws-dev` 回退到 `$ws-plan`
+   - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
+
+输出模板：
+- `Root:` <path>
+- `Found:` <files>
+- `Task intent:` <分类>
+- `Binding:` <清晰 / 缺失项>
+- `Route:` <$ws-... 或 clarify>
+- `Why:` <一句到三句>
+- `Next:` <继续执行对应 skill，或提出澄清问题>

package/templates/workspace/.agents/skills/ws-commit/SKILL.md

@@ -21,6 +21,29 @@ description: 提交（当前分支可直提；submodule 感知；先审计/门
 - commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
 - 若启用了 `.githooks/commit-msg`：默认会提示优先中文；只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
 
+阶段定位：
+- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
+
+必需输入：
+- 当前分支与 staged diff
+- `$ws-review` 生成的审计证据
+- `aiws validate . --stamp` 生成的校验证据
+- 用户确认后的 commit message
+
+必需输出：
+- `证据（Evidence）:` review 文件路径 + validate stamp 路径
+- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
+- `提交信息（Commit）:` 最终提交信息
+
+阻断条件：
+- 没有 staged changes
+- submodule 工作区不干净或 detached 处理不完整
+- 用户未确认 commit message
+- validate 失败
+
+完成判定：
+- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
+
 执行步骤（建议）：
 1) 运行 `$ws-preflight`（确保真值文件就绪）。
 2) 运行 `$ws-review`（优先生成审计证据：`changes/<change-id>/review/codex-review.md`；无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`）。

package/templates/workspace/.agents/skills/ws-delegate/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ws-delegate
+description: 原生多 agent 委托入口（Codex 优先；先定义角色/边界/工件/降级，再决定是否委托）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 治理约束下，只有在任务已绑定且 scope 可控时，才使用当前工具的原生多 agent / sub-agent 能力；否则明确降级为单 agent + 协同工件模式。
+
+阶段定位：
+- implementation / review 的辅助入口；它不是独立 workflow 阶段，也不能绕过 `ws-plan`、`ws-dev`、`ws-review`、`ws-finish`。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- delegation contract：`packages/spec/docs/workflow-delegation-contracts.md`
+- 当前任务已绑定 `Req_ID` / change / Verify 入口
+- 拟委托子任务的角色划分、读写边界、artifact 目标与 fallback
+
+必需输出：
+- `Delegation Plan:` 逐项写清 role / task / readScope / writeScope / artifactTargets / fallback
+- `Execution Mode:` 明确是 `native multi-agent` 还是 `fallback single-agent`
+- `Evidence:` 委托产物路径（`analysis/` / `patches/` / `review/` / `evidence/`）
+- `Next:` 收敛后应回到 `ws-dev`、`ws-review`、`ws-commit` 或 `ws-finish`
+
+阻断条件：
+- 无法绑定到 `Req_ID` / change / Verify
+- 没有明确的 `writeScope` / `artifactTargets`
+- 当前工具缺少稳定 native delegation 能力，且你又不能接受降级执行
+- 任务规模太小，引入委托只会增加复杂度
+
+完成判定：
+- 已经明确本次是否适合委托
+- 若适合：delegation plan 已声明并执行，产物回收到 AIWS 约定路径
+- 若不适合：已明确降级原因，并回到单 agent 流程继续执行
+
+步骤（建议）：
+1) 先读取真值文件与 `packages/spec/docs/workflow-delegation-contracts.md`，确认这不是“为了多 agent 而多 agent”。
+2) 判断当前任务是否真的需要委托：
+   - 需要并行的只读探索
+   - 需要把实现与审查拆开
+   - 有明确、互不重叠的写入边界
+   - 委托收益大于协调成本
+3) 先写 `Delegation Plan:`，至少包含：
+   - `role`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+4) 若当前环境支持原生多 agent：
+   - 优先把探索型工作交给 `explorer`
+   - 只把显式授权的文件范围交给 `worker`
+   - 至少保留一个独立 `reviewer`
+   - 由主 agent / `integrator` 统一收敛结果
+5) 若当前环境不支持，或无法稳定约束 scope：
+   - 明确输出 `Execution Mode: fallback single-agent`
+   - 仍按 AIWS 协同工件约定执行：
+     - `changes/<id>/analysis/`
+     - `changes/<id>/patches/`
+     - `changes/<id>/review/`
+     - `changes/<id>/evidence/`
+6) 不论是否启用原生多 agent，都不要跳过：
+   - 需求归因
+   - 验证命令
+   - review convergence
+   - finish / handoff gate
+
+Codex 优先说明：
+- 若当前环境支持原生多 agent / sub-agent，就按 delegation contract 显式拆 role 与 scope。
+- 若不支持，或你无法保证写边界，直接降级，不临时发明新的 runtime/controller。
+
+安全：
+- 不把 `aiws` 变成统一 orchestrator。
+- 不让 delegated agent 越权写未授权文件。
+- 不把 `patches/` 视为“已合并代码”。

package/templates/workspace/.agents/skills/ws-deliver/SKILL.md

@@ -25,6 +25,28 @@ description: 交付（submodules + superproject 分步提交，并安全合并
    - 该 repo 的 `git diff --staged`
    并让用户确认 commit message（每个 repo 单独确认）。
 
+阶段定位：
+- delivery 阶段；负责在多 repo / submodule 场景下完成顺序提交、证据收敛和最终合并前准备。
+
+必需输入：
+- 当前 `change/<change-id>` 上下文
+- 若存在 submodule：`.gitmodules` + `changes/<change-id>/submodules.targets`
+- 各 repo 当前状态与 staged diff
+
+必需输出：
+- `Submodules:` 每个 submodule 的提交摘要
+- `Superproject:` 主仓库提交摘要
+- `Evidence:` validate stamp 与持久证据路径
+- `Next:` 进入 `$ws-finish` 或 `aiws change finish`
+
+阻断条件：
+- 不在正确的 change 上下文
+- submodule branch / targets 真值不完整
+- 任一 repo 未确认 commit message 或存在未处理冲突
+
+完成判定：
+- submodule 与 superproject 提交都已完成，证据已收敛，且可以安全进入 finish 阶段。
+
 建议流程（按顺序）：
 
 ## 0) submodule branch 真值检查（减少 detached 与人为差异）

package/templates/workspace/.agents/skills/ws-dev/SKILL.md

@@ -7,6 +7,29 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 
 目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
 
+阶段定位：
+- implementation 阶段；负责在既定计划/需求绑定下完成最小实现与验证。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前任务的归因目标（`Req_ID` 或 `Problem_ID`）
+- 若为 medium/complex：已通过 `$ws-plan` / `$ws-plan-verify` 的计划
+- 当前 `change/<change-id>` 上下文或等价变更归因
+
+必需输出：
+- `变更文件（Changed）:` 实际改动清单
+- `验证（Verify）:` 实际运行的命令与结果说明
+- `证据（Evidence）:` `plan/...`、`changes/<change-id>/...`、`.agentdocs/tmp/...` 等证据路径
+- `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
+
+阻断条件：
+- 无法把改动归因到 `REQUIREMENTS.md` 或问题单
+- 没有可复现验证入口
+- 需要创建 change 上下文但当前工作区状态不允许安全切换
+
+完成判定：
+- 改动已落盘、验证已执行或明确未执行原因、证据路径可回放，并可进入 review/commit 阶段。
+
 建议流程：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
    - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
@@ -117,11 +140,16 @@ cat "${targets}"
 ```
    - 若你明确要在 superproject 直接切分支：`aiws change start <change-id> --hooks --switch`（仅在存在 `.gitmodules` 时有意义；会尝试让 submodules 工作区跟随 superproject 指针）
    - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
-3) 如涉及需求调整：先做需求评审（可用 `$ws-req-review`）→ 用户确认后再做需求落盘（可用 `$ws-req-change`）（避免需求漂移）。
-4) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
-5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
-6) 多步任务（≥2 步）：使用 `update_plan` 工具跟踪 `pending → in_progress → completed`，每完成一步立即更新（不要事后批量更新）。
-7) 提交前强制门禁（commit/push hooks 也会阻断）：
+3) 若需要外部 / 子 agent 协作：
+   - 分析结论落盘到 `changes/<change-id>/analysis/`
+   - patch 草案落盘到 `changes/<change-id>/patches/`
+   - 不要把 `patches/` 当成“已应用代码”；主 agent 必须先审查再决定是否采用
+   - 若采用了委托结果，后续在 `ws-review` 或 `changes/<change-id>/review/` 中收敛最终结论
+4) 如涉及需求调整：先做需求评审（可用 `$ws-req-review`）→ 用户确认后再做需求落盘（可用 `$ws-req-change`）（避免需求漂移）。
+5) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
+6) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
+7) 多步任务（≥2 步）：使用 `update_plan` 工具跟踪 `pending → in_progress → completed`，每完成一步立即更新（不要事后批量更新）。
+8) 提交前强制门禁（commit/push hooks 也会阻断）：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
   ./node_modules/.bin/aiws validate .
@@ -131,7 +159,8 @@ else
   npx @aipper/aiws validate .
 fi
 ```
-8) 交付收尾（推荐，减少手动 merge 出错）：运行 `$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
+9) 若使用了协同工件，交付前建议执行 `aiws change evidence <change-id>`，把 review / validate / collaboration summary 收敛到 `changes/<change-id>/evidence/`。
+10) 交付收尾（推荐，减少手动 merge 出错）：运行 `$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
 
 输出要求：
 - `变更文件（Changed）:` 文件清单

package/templates/workspace/.agents/skills/ws-finish/SKILL.md

@@ -17,6 +17,30 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 - 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
 - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
 
+阶段定位：
+- finish 阶段；负责把已提交的 change 安全合并回目标分支，并按约束完成 push / worktree cleanup。
+
+必需输入：
+- 干净的当前工作区
+- 已提交完成的 `change/<change-id>`
+- 若存在 submodule：`.gitmodules` 与 `changes/<change-id>/submodules.targets`
+- 当前 push 目标说明（remote / branch）
+
+必需输出：
+- `Merge:` `aiws change finish` 的结果（from / into）
+- `Push:` 实际 remote / branch 或未 push 原因
+- `Worktree cleanup:` 清理结果
+- `Evidence:` validate stamp / evidence / state 路径
+
+阻断条件：
+- 工作区不干净
+- 缺失 submodule branch / targets 真值
+- fast-forward 失败
+- 子模块目标分支无法安全 push
+
+完成判定：
+- change 已安全合并回目标分支，必要的 push 与 worktree cleanup 已完成或明确说明未完成原因。
+
 建议步骤：
 0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
 ```bash

package/templates/workspace/.agents/skills/ws-frontend-design/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: ws-frontend-design
+description: 前端设计实现（用于视觉型 landing page / 网站 / 应用界面 / demo / prototype；强调构图、层级、图像、动效与克制，不做通用卡片墙）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在 AIWS 约束下交付一个可运行、可验证、视觉方向明确的前端界面
+- 先做信息层级与构图，再做组件细节；避免“先堆卡片再补样式”
+- 在品牌页与产品页之间做正确取舍：品牌页重视觉锚点，产品页重可操作性
+
+非目标（强制）：
+- 不绕过 `$ws-preflight`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`
+- 不因为“追求设计感”而重写无关页面、改动无关设计系统或新增大面积依赖
+- 不默认把已有产品后台改成营销页；dashboard / admin / workspace 优先 utility copy
+- 不把 prompt 语言、设计说明、占位废话直接写进 UI
+
+适用场景：
+- 用户要做 landing page、品牌站、活动页、marketing 页面、demo、prototype、game UI
+- 用户要把现有前端界面做成“视觉主导、层级清晰、记忆点强”的版本
+- 用户明确要求美化、重做、提质、增强 art direction / hierarchy / motion
+
+前置（建议顺序）：
+1) 先运行 `$ws-preflight`。
+2) 判断任务类型（必须选一个）：
+   - `landing`：品牌/营销/活动页
+   - `app-ui`：dashboard / admin / workspace / 工具界面
+   - `polish-only`：不改信息架构，只做视觉提质
+3) 判断设计边界（必须说明）：
+   - `net-new`：全新页面，可建立完整视觉语言
+   - `existing-system`：已有设计系统/品牌规范，优先复用
+4) 若任务达到 medium / complex：先用 `$ws-plan` 落盘计划，再进入实现。
+
+开始编码前，先写三项（不要跳过）：
+- `Visual thesis:` 一句话写清 mood / material / energy
+- `Content plan:` `hero -> support -> detail -> final CTA`（若是 app-ui，则改为 `workspace -> nav -> context -> action`）
+- `Interaction thesis:` 2-3 个动效想法；说明它们如何改善层级/氛围/可感知性
+
+设计默认值：
+- 从构图开始，不从组件库开始
+- 第一屏优先做成海报感（poster），不是文档感（document）
+- 默认先找一个强视觉锚点：大图、主视觉平面、关键产品画面、主数据工作区
+- 默认不做卡片墙；优先 section、column、divider、media block、list、plain layout
+- 默认最多两套字体、一种强调色；若已有品牌系统，优先跟随现有 token
+- 优先靠留白、尺度、裁切、对比、对齐建立层级，再考虑装饰
+
+landing 规则：
+1) 默认结构：
+   - Hero：品牌/产品名、承诺、CTA、一个主视觉
+   - Support：一个具体能力 / 证明点 / offer
+   - Detail：氛围、流程、产品深度或故事
+   - Final CTA：开始、注册、联系、访问
+2) Hero 强约束：
+   - 一个 section 只承载一个 dominant idea
+   - 默认使用 full-bleed hero；只有内层文字列需要约束宽度
+   - 品牌名优先级高于 headline；headline 高于 body；body 高于 CTA
+   - 默认不要 hero cards、stat strips、logo clouds、pill soup、floating dashboards
+   - headline 在 desktop 约 2-3 行；mobile 一眼读完
+   - 若有固定 header，它占用首屏预算；不要让 header + hero 超出初始 viewport
+   - 若去掉主视觉后首屏仍几乎成立，说明图像太弱
+
+app-ui 规则：
+- 默认偏克制：少颜色、少 chrome、清晰栅格、密度适中、信息可扫读
+- 优先组织为：`primary workspace -> navigation -> secondary context/inspector -> action`
+- 只有当 card 本身就是交互容器时才用 card；否则尽量改回 plain layout
+- 不要把 routine product UI 做成营销落地页
+- 文案优先 orientation / status / action：
+  - 好例子：`Selected KPIs`、`Plan status`、`Last sync`
+  - 差例子：首页口号、情绪化隐喻、执行摘要横幅
+
+图像与媒体：
+- 图像必须承担叙事任务，不能只是补背景
+- 品牌页/空间页/生活方式产品优先真实感强的图，而不是抽象 3D / 假 dashboard
+- 选图时优先有稳定明暗区，便于文字落位
+- 避免图里自带抢戏的 logo、signage、碎字、边框 UI
+- 若需要多个场景，优先多张图，不要拼贴大杂烩
+
+文案：
+- 用产品语言，不用设计评论语言
+- headline 负责主要意义；supporting copy 通常一句话够了
+- 每个 section 只负责一件事：explain / prove / deepen / convert
+- 如果删掉 30% 文案后更清楚，就继续删
+
+动效：
+- 视觉型页面至少给 2-3 个“有感但克制”的动效：
+  - 一个 hero 入场序列
+  - 一个 scroll-linked / sticky / depth 效果
+  - 一个 hover / reveal / layout transition
+- 动效必须改善层级或氛围，不能只是热闹
+- 要兼顾 mobile 流畅度；支持 `prefers-reduced-motion`
+
+工程约束（强制）：
+- 先读现有代码，再决定是否沿用已有 design tokens / 组件 / 动效库
+- `existing-system` 场景下，优先复用已有视觉语言；不要无故“整站改头换面”
+- 不新增字体、图片资源、动画库、运行时依赖，除非明确写出原因、来源、license/成本与回滚方式
+- 所有文字覆盖在图像上时，必须保证对比度与点击区域可用
+- 必须同时考虑 desktop / mobile；不要只调一个 viewport
+- 未运行不声称已运行；验证命令优先引用 `AI_WORKSPACE.md`
+
+硬规则：
+- No cards by default
+- No hero cards by default
+- No generic SaaS card grid as first impression
+- No more than one dominant idea per section
+- No more than two typefaces without a clear reason
+- No more than one accent color unless the existing product already has a strong system
+- No decorative gradients behind routine product UI
+- No busy imagery behind text
+- No filler copy
+
+实现检查（交付前自检）：
+- 第一屏能否一眼看出品牌/产品是什么
+- 是否存在一个明确视觉锚点
+- 只扫标题是否能理解页面
+- 每个 section 是否只有一个职责
+- card 是否真有必要
+- 动效是否真的提升层级/氛围
+- 去掉装饰阴影后，页面是否仍然成立
+
+输出要求：
+- `Mode:` `landing | app-ui | polish-only`
+- `Visual thesis:` 一句话
+- `Changed:` 改动文件清单
+- `Verify:` 实际运行命令 + 预期结果
+- `Evidence:` 相关 `plan/...`、`changes/<change-id>/...` 或截图/审计路径

package/templates/workspace/.agents/skills/ws-handoff/SKILL.md

@@ -7,12 +7,33 @@ description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
 
 目标：
 - 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
+- 若存在协同工件：在 handoff 中一并概述 `analysis/`、`patches/`、`review/`、`evidence/`
 - 指引在归档与依赖场景下如何使用 handoff
 
 说明：
 - `handoff.md` 由 `aiws change archive` 自动生成：`changes/archive/<date>-<change-id>/handoff.md`
 - `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
 
+阶段定位：
+- handoff / archive 阶段；负责把已完成 change 的上下文压缩成后续协作者可直接接手的说明。
+
+必需输入：
+- 当前或已归档的 `change/<change-id>`
+- 对应 archive 目录或准备归档的 change 工件
+
+必需输出：
+- `Change_ID:` 当前交接对象
+- `Handoff:` `changes/archive/.../handoff.md`
+- `Next:` 推荐后续 change / `Depends_On` 关系
+
+阻断条件：
+- 无法定位目标 change
+- 未归档且无法执行 `aiws change archive <change-id>`
+- `handoff.md` 无法生成或读取
+
+完成判定：
+- 下一位协作者可以只依赖 `handoff.md` 和绑定信息继续工作，而不需要回溯整段会话。
+
 执行建议：
 1) 先运行 `$ws-preflight`。
 2) 若本 change 已完成并准备归档：运行 `aiws change archive <change-id>`（会先做严格校验，并移动目录到 `changes/archive/`，同时生成 `handoff.md`）。
@@ -23,9 +44,9 @@ ls -1 changes/archive/*-"${change_id}"/handoff.md
 sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
 ```
 4) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
+5) 若本 change 使用了外部 / 子 agent 协作：确认关键结论已经进入 `review/` 或 `evidence/`，避免 handoff 只留下原始 patch/分析文件而没有最终结论。
 
 输出要求：
 - `Change_ID:` <change-id>
 - `Handoff:` `changes/archive/.../handoff.md`
 - `Next:` 若还有后续工作，建议创建新 change 并在其 `Depends_On` 引用本 change
-