@aipper/aiws-spec 0.0.28 → 0.0.30

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

@@ -1,52 +1,18 @@
 ---
 name: ws-handoff
-description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
+description: Thin wrapper for `aiws handoff`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-handoff
 
-目标：
-- 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
-- 若存在协同工件：在 handoff 中一并概述 `analysis/`、`patches/`、`review/`、`evidence/`
-- 指引在归档与依赖场景下如何使用 handoff
+Thin skill wrapper. Delegates to `aiws handoff`. See `aiws handoff --help` for details.
 
-说明：
-- `handoff.md` 默认由 `aiws change finish --push` 自动归档时生成：`changes/archive/<date>-<change-id>/handoff.md`
-- `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
-
-阶段定位：
-- handoff / archive 阶段；负责查看或补充已归档 change 的交接说明。
-
-必需输入：
-- 已归档的 `change/<change-id>`
-- 对应 archive 目录
-
-必需输出：
-- `Change_ID:` 当前交接对象
-- `Handoff:` `changes/archive/.../handoff.md`
-- `Next:` 推荐后续 change / `Depends_On` 关系
-
-阻断条件：
-- 无法定位目标 change
-- `handoff.md` 无法生成或读取
-
-完成判定：
-- 下一位协作者可以只依赖 `handoff.md` 和绑定信息继续工作，而不需要回溯整段会话。
-
-执行建议：
-1) 先运行 `$ws-preflight`。
-2) 先确认本 change 已通过 `aiws change finish <change-id> --push` 完成自动归档。
-3) 查看 handoff：
 ```bash
-change_id="<change-id>"
-ls -1 changes/archive/*-"${change_id}"/handoff.md
-sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws handoff
+elif command -v aiws >/dev/null 2>&1; then
+  aiws handoff
+else
+  npx @aipper/aiws handoff
+fi
 ```
-4) 若是历史/异常场景，尚未归档且需要手工恢复，再运行 `aiws change archive <change-id>`。
-5) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
-6) 若本 change 使用了外部 / 子 agent 协作：确认关键结论已经进入 `review/` 或 `evidence/`，避免 handoff 只留下原始 patch/分析文件而没有最终结论。
-
-输出要求：
-- `Change_ID:` <change-id>
-- `Handoff:` `changes/archive/.../handoff.md`
-- `Next:` 若还有后续工作，建议创建新 change 并在其 `Depends_On` 引用本 change

package/templates/workspace/.opencode/skills/ws-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-intake
-description: 计划前置澄清（逐条冻结问题并产出 intake 草案，供 ws-plan 消费）
+description: 使用时机：新需求需要逐条澄清、冻结问题时。触发词：需求澄清、intake、冻结问题、前期沟通。注意：需求已冻结直接进 ws-plan。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
@@ -10,6 +10,35 @@ description: 计划前置澄清（逐条冻结问题并产出 intake 草案，
 - 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论。
 - 产出一份可被 `/ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`。
 
+## 发散-收敛两子阶段
+
+当需求模糊、方向不明确时，intake 分两子阶段推进：
+
+### 发散阶段（Explore）
+- 目标：快速探索 2-3 个可能方向，不深入任何单一方向
+- 输出：每个方向的 1-2 段摘要 + 关键风险 + 依赖
+- 时限：不超过 3 轮对话
+
+### 收敛阶段（Converge）
+- 目标：从发散结果中选择 1 个方向，逐条冻结具体问题
+- 回到标准"一题一线程"模式
+- 把发散产出的摘要作为收敛的输入上下文
+
+触发条件：用户说"不确定"/"多个方向"/"帮我分析" 等模糊表达。
+非模糊需求不需要经过发散阶段，直接进入收敛。
+
+## 核心原则：一次一个问题
+
+- 每轮只推进 1 个 `Open Questions` 中的问题
+- 当前问题未标记 `frozen` 或 `deferred` 前，不进入下一题
+- 输出格式：`Current question → Why it matters → Options → Exit condition`
+- 用户选择后立即写盘更新草案，再进入下一题
+
+**队列保护**：若用户一次提出多个问题，必须显式建队（Queue），逐一处理——不可同时推进多个维度。队列格式：
+- Queue: [Q1: ..., Q2: ..., Q3: ...]
+- Current: Q1
+- Status: [open/in_discussion/frozen/deferred] per item
+
 执行要求：
 1) 先读 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，必要时先 `/ws-preflight`。
 2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
@@ -18,8 +47,9 @@ description: 计划前置澄清（逐条冻结问题并产出 intake 草案，
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
-   - `Exit condition:`
-5) 当前问题在没有被标记成 `frozen` 或 `deferred` 前，不进入下一题。
+    - `Exit condition:`
+- 每个问题独立线程：在未标记 frozen/deferred 前，不进入下一题。问答往返不限轮数，但一次只处理一个维度的决策。
+5) 若用户一次提出多个问题，必须显式排队：列出所有问题编号，按顺序逐个处理；不得同时推进多个问题的讨论。输出格式：`Queued questions: #1, #2, ...  | Current: #1`
 6) 每轮都要把 intake 草案写盘，至少包含：
    - `Context`
    - `Open Questions`
@@ -28,4 +58,13 @@ description: 计划前置澄清（逐条冻结问题并产出 intake 草案，
    - `Draft Scope`
    - `Draft Verify`
    - `Ready for ws-plan: yes/no`
-7) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。
+7) 错误状态节点（Error States）：
+   - 在 intake 草案中专设 `Error States` 小节，覆盖已知失败模式：
+     - 网络/超时/第三方依赖不可用时的系统行为
+     - 数据一致性（并发写入、部分失败、脏数据）
+     - 输入校验边界（空、超大、非预期类型）
+   - 若识别到需要回滚的场景：在 `Error States` 中写明回滚条件与回滚方式。
+8) 回滚规范（Rollback Spec）：
+   - 当 intake 涉及现有数据迁移、API 契约变更、配置漂移修复时，必须包含 `Rollback Plan` 小节。
+   - `Rollback Plan` 至少包含：触发条件、回滚步骤、验证回滚成功的方式、副作用清单。
+9) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。

package/templates/workspace/.opencode/skills/ws-migrate/SKILL.md

@@ -1,54 +1,18 @@
 ---
 name: ws-migrate
-description: 迁移（补齐/升级 AIWS 工作区文件）
+description: Thin wrapper for `aiws migrate`
 ---
 
-用中文输出；命令与路径保持原样不翻译。
+# ws-migrate
 
-目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+Thin skill wrapper. Delegates to `aiws migrate`. See `aiws migrate --help` for details.
 
-执行（在项目根目录）：
-```bash
-if [[ -f ".aiws/manifest.json" ]]; then
-  if [[ -x "./node_modules/.bin/aiws" ]]; then
-    ./node_modules/.bin/aiws update .
-  elif command -v aiws >/dev/null 2>&1; then
-    aiws update .
-  else
-    npx @aipper/aiws update .
-  fi
-else
-  if [[ -x "./node_modules/.bin/aiws" ]]; then
-    ./node_modules/.bin/aiws init .
-  elif command -v aiws >/dev/null 2>&1; then
-    aiws init .
-  else
-    npx @aipper/aiws init .
-  fi
-fi
-
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate .
-elif command -v aiws >/dev/null 2>&1; then
-  aiws validate .
-else
-  npx @aipper/aiws validate .
-fi
-
-git config core.hooksPath .githooks
-```
-
-回滚（恢复最近一次快照）：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws rollback . latest
+  ./node_modules/.bin/aiws migrate
 elif command -v aiws >/dev/null 2>&1; then
-  aiws rollback . latest
+  aiws migrate
 else
-  npx @aipper/aiws rollback . latest
+  npx @aipper/aiws migrate
 fi
 ```
-
-约束：
-- 不写入任何 secrets。
-- 不执行破坏性命令。

package/templates/workspace/.opencode/skills/ws-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-plan
-description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
+description: 使用时机：需要生成执行计划、建立 change 绑定时。触发词：计划、规划、方案、设计、change。注意：需求未冻结先用 ws-intake。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
@@ -52,41 +52,15 @@ OpenCode + oMo 优先策略：
    - 若检测到 oMo：优先让 `planner-sisyphus` 生成 planning draft；若需要补结构探索，再委托 `@explore` / `@librarian`。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
 3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
-4) 识别或建立主索引 / change 上下文：
+ 4) 识别或建立主索引 / change 上下文：
    - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
    - 若缺失关键绑定：先补齐 proposal（至少 `Change_ID`、`Req_ID|Problem_ID`、`Contract_Row`）再继续生成计划
-   - 若当前不在 `change/<change-id>` 分支 / worktree，且本次任务需要新建 change：先调用 `aiws change start` 建立上下文，再继续写 plan
-   - 推荐顺序：
-     - 工作区已存在未提交改动：不要先写 `plan/...`；先停下来说明原因，并要求用户先 commit/stash，或改用已有 change 上下文
-     - 仓库已有提交：优先创建独立 worktree；若仓库声明了 submodules，加上 `--submodules`
-     - 仓库尚无提交 / 不满足 worktree 前置条件：回退为 `--no-switch`
-```bash
-change_id="<change-id>"
-if [[ -n "$(git status --porcelain)" ]]; then
-  echo "error: working tree dirty before ws-plan creates change context"
-  echo "hint: commit/stash first, or continue inside an existing change/<change-id> context"
-  exit 2
-fi
-
-has_commits=0
-git rev-parse --verify HEAD >/dev/null 2>&1 && has_commits=1
-
-has_submodules=0
-if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
-  has_submodules=1
-fi
-
-if [[ "${has_commits}" -eq 1 ]]; then
-  if [[ "${has_submodules}" -eq 1 ]]; then
-    aiws change start "${change_id}" --hooks --worktree --submodules
-  else
-    aiws change start "${change_id}" --hooks --worktree
-  fi
-else
-  aiws change start "${change_id}" --hooks --no-switch
-fi
-```
-   - 若上一步创建了 worktree：后续所有读取/写入都必须切到 `aiws change start` 输出的 `worktree:` 路径中进行；不要把 `plan/...` 写回原工作区
+   - 若当前不在 `change/<change-id>` 分支 / worktree，且本次任务需要新建 change：
+     ```bash
+     bash .opencode/scripts/ws-plan-setup-worktree.sh <change-id>
+     ```
+     脚本自动处理：dirty 检查、commits/submodules 检测、worktree 创建。
+   - 若脚本创建了 worktree：后续所有读取/写入都必须切到 `aiws change start` 输出的 `worktree:` 路径中进行；不要把 `plan/...` 写回原工作区
 5) 生成计划文件：
    - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
    - 若 `plan/` 不存在先创建
@@ -100,10 +74,12 @@ fi
    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
    - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
-   - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
+    - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
+    - 若 intake 草案包含 `Error States` 或 `Rollback Plan`：必须显式引用并纳入本计划的 `Risks & Rollback` 中，不能丢弃 intake 已识别的问题
    - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
 7) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
 8) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
+   - 通过后：标记 `[workflow-state:plan:DONE]` 或 `[workflow-state:gate:plan_passed]`，表示 plan 阶段已收敛。
 9) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
 10) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
 
@@ -120,26 +96,10 @@ oMo 回退：
     - 第 1 列：submodule path（例如 `vendor/foo`）
     - 第 2 列：target branch（例如 `release/channel-a`）
     - 第 3 列（可选）：remote 名（默认 `origin`）
-- 生成模板（建议在确认 `Change_ID` 后执行；如文件已存在先备份再覆盖）：
-```bash
-change_id="<change-id>"
-targets="changes/${change_id}/submodules.targets"
-mkdir -p "changes/${change_id}"
-if [[ -f "${targets}" ]]; then
-  bak="${targets}.bak.$(date -u +%Y%m%d-%H%M%SZ)"
-  cp "${targets}" "${bak}"
-  echo "info: backup: ${bak}"
-fi
-: > "${targets}"
-echo "# path<TAB>target_branch<TAB>remote(optional, default=origin)" >> "${targets}"
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-  [[ "${b:-}" == "." ]] && b="$(git branch --show-current)"  # '.' means "follow superproject branch"
-  printf "%s\t%s\t%s\n" "${sub_path}" "${b:-<fill-me>}" "origin" >> "${targets}"
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-echo "ok: wrote ${targets}"
-```
+ - 生成模板：
+   ```bash
+   bash .opencode/scripts/ws-plan-gen-submodule-targets.sh <change-id>
+   ```
 - 计划里必须写清：本次交付选择的 `targets` 内容，以及后续在 `$ws-dev` 进入编码前会把 submodules 挂到 `aiws/pin/<target_branch>`（必要时先 `fetch`）。
 
 输出要求：

package/templates/workspace/.opencode/skills/ws-plan-verify/SKILL.md

@@ -1,61 +1,18 @@
 ---
 name: ws-plan-verify
-description: 计划质检（执行前检查计划是否过长/跑偏，并给出最小修正清单）
+description: Thin wrapper for `aiws plan-verify`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-plan-verify
 
-目标：
-- 在进入 `$ws-dev` 前，对 `plan/...` 与 `changes/<change-id>/proposal.md` 做一次“硬约束”质检
-- 避免计划过长、步骤不够具体、验证不可复现、与需求合同绑定不一致
-- 失败时只给最小修正项，修完后再进入实现
+Thin skill wrapper. Delegates to `aiws plan-verify`. See `aiws plan-verify --help` for details.
 
-适用时机：
-- 已执行过 `$ws-plan`，且准备开始编码
-- 或用户反馈“计划太长/容易跑偏”，需要先压缩并对齐
-
-阶段定位：
-- planning gate；负责在编码前检查计划是否满足 change 严格契约。
-
-必需输入：
-- 当前 `plan/...`
-- `changes/<change-id>/proposal.md`
-- 当前 change 上下文
-
-必需输出：
-- `Quality gate:` pass/fail
-- `Fix list:` 最小修正项
-- `Next:` 通过则 `$ws-dev`，未通过则继续修正并复跑
-
-阻断条件：
-- 无法定位当前 change 或计划文件
-- `aiws change validate <change-id> --strict` 未通过
-
-完成判定：
-- 计划满足严格门禁，且后续实现可以在不补需求/补绑定的情况下直接开始。
-
-执行步骤（建议）：
-1) 先运行 `$ws-preflight`。
-2) 识别 change 上下文：
-   - 优先从当前分支推断 `change/<change-id>`
-   - 若无法推断：读取 `changes/*/proposal.md` 中的 `Change_ID`，并让用户确认本次要质检的 change
-3) 运行严格门禁（这是硬约束入口）：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change validate <change-id> --strict
+  ./node_modules/.bin/aiws plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change validate <change-id> --strict
+  aiws plan-verify
 else
-  npx @aipper/aiws change validate <change-id> --strict
+  npx @aipper/aiws plan-verify
 fi
 ```
-4) 若失败：按报错逐条修正 `proposal.md` / `plan/...`，优先级如下：
-   - 先修绑定：`Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
-   - 再修计划质量：必需章节、步骤数量、步骤具体性、验证命令与预期
-5) 复跑 strict 校验，直到通过。
-6) 输出“可执行最小计划摘要”（3-8 步），再进入 `$ws-dev`。
-
-输出要求：
-- `Quality gate:` pass/fail
-- `Fix list:` 仅保留必须修改项（按阻断级别排序）
-- `Next:` 通过后建议 `$ws-dev`；未通过则继续修正并复跑 strict

package/templates/workspace/.opencode/skills/ws-preflight/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-preflight
-description: 预检（提交前快速检查与建议）
+description: 使用时机：新会话开始、仓库首次操作时。触发词：预检、初始化、首次、preflight、检查环境。注意：已经开工可直接 ws-dev。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

package/templates/workspace/.opencode/skills/ws-pull/SKILL.md

@@ -1,119 +1,18 @@
 ---
 name: ws-pull
-description: 拉取并对齐 submodules（避免 detached；减少人为差异）
+description: Thin wrapper for `aiws pull`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-pull
 
-背景：
-- Git submodule 在别的电脑 `git submodule update` 后常见现象是子模块处于 detached HEAD（因为主仓库记录的是固定 gitlink commit）。
-- detached 本身不一定是错，但会增加“需要手动切分支/容易忘”的操作差异。
+Thin skill wrapper. Delegates to `aiws pull`. See `aiws pull --help` for details.
 
-目标：
-- 安全拉取 superproject（默认只允许 fast-forward）
-- 初始化/同步 submodules（`--init --recursive`）
-- 在**不改动 superproject gitlink commit** 的前提下，尽量把每个 submodule 从 detached HEAD “挂回”到一个**确定的目标分支**（仅当该分支包含 gitlink commit 时）
-- 若未配置 `.gitmodules` 的 `submodule.<name>.branch`：保持 detached，并提示先运行 `$ws-submodule-setup`
-
-安全约束（强制）：
-- 不执行破坏性命令（不 `reset --hard` 主仓库；不改动远端）
-- 不自动提交/不自动 push
-- 若工作区不干净：停止并要求用户先 commit 或 stash（不要自动处理）
-
-执行步骤（建议）：
-0) 输出上下文：
 ```bash
-git rev-parse --show-toplevel
-git branch --show-current
-git status --porcelain
-```
-若 `git status --porcelain` 非空：停止，要求用户先清理工作区（commit 或 stash）。
-
-1) 拉取 superproject（默认只允许 fast-forward，避免隐式 merge/rebase）：
-```bash
-git pull --ff-only
-```
-若失败（需要 merge/rebase）：停止并向用户解释原因，让用户明确选择 `git pull --rebase` 或手动处理。
-
-2) 同步并更新 submodules 到 superproject 记录的 gitlink commit：
-```bash
-if [[ -f .gitmodules ]]; then
-  git submodule sync --recursive
-  git submodule update --init --recursive
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws pull
+elif command -v aiws >/dev/null 2>&1; then
+  aiws pull
 else
-  echo "[info] no .gitmodules"
+  npx @aipper/aiws pull
 fi
 ```
-
-3) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”，减少手工操作差异：
-
-说明：
-- 该步骤不会改变 superproject 的 gitlink commit（也不会让主仓库出现“submodule modified”）。
-- 只在目标分支包含该 gitlink commit 时才执行“挂回”；否则保持 detached 并提示原因。
-- 为了避免 origin 分支较多时“猜错分支”，本步骤**只在** `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行“挂回分支”；否则保持 detached 并提示先运行 `$ws-submodule-setup` 对齐配置。
-
-```bash
-if [[ -f .gitmodules ]]; then
-  base_branch="$(git branch --show-current)"
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-    | while read -r key sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      name="${key#submodule.}"
-      name="${name%.path}"
-      echo "== submodule: ${sub_path} (${name}) =="
-
-      sub_sha="$(git rev-parse "HEAD:${sub_path}" 2>/dev/null || true)"
-      if [[ -z "${sub_sha:-}" ]]; then
-        echo "[warn] failed to read gitlink sha for ${sub_path}"
-        continue
-      fi
-
-      cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-      if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-      if [[ -z "${cfg_branch:-}" ]]; then
-        echo "[warn] ${sub_path}: missing .gitmodules submodule.${name}.branch; keep detached (run ws-submodule-setup to set it)"
-        continue
-      fi
-
-      target_branch="${cfg_branch}"
-      pin_branch="aiws/pin/${target_branch}"
-
-      git -C "${sub_path}" fetch origin --prune || true
-
-      if git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-        if git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-          # 不改动现有分支（避免把已有 main/master 等分支强行指回旧 commit）
-          # 仅创建/更新一个 AIWS 专用 pin 分支指向 gitlink commit，从 detached “挂回分支”。
-          git -C "${sub_path}" checkout -B "${pin_branch}" "${sub_sha}"
-          git -C "${sub_path}" branch --set-upstream-to "origin/${target_branch}" "${pin_branch}" >/dev/null 2>&1 || true
-          echo "[ok] attached ${sub_path} to ${pin_branch} (upstream=origin/${target_branch}) at ${sub_sha}"
-        else
-          echo "[warn] ${sub_path}: ${sub_sha} is not in origin/${target_branch}; keep detached"
-        fi
-      else
-        echo "[warn] ${sub_path}: origin/${target_branch} not found; keep detached"
-      fi
-
-      git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
-      git -C "${sub_path}" status -sb || true
-    done
-fi
-```
-
-4) 一次性配置（方案 2）：为每个 submodule 写入跟踪分支，便于团队统一（需要用户确认，会改动 `.gitmodules`）：
-```bash
-# 示例：把某个 submodule 固定跟踪 main（会写入 .gitmodules 的 submodule.<name>.branch）
-git submodule set-branch --branch main <sub_path>
-
-# 提示：该变更需要提交到 superproject
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branch"
-```
-建议：
-- 只有当团队明确希望“子模块按分支滚动”（而不是锁定固定 commit）时，才采用方案 2。
-- 若只是想避免 detached 但仍锁定 gitlink commit：优先使用步骤 3（不改 `.gitmodules`）。
-- 推荐用 `$ws-submodule-setup` 交互式对齐所有 submodules 的 branch，并提交 `.gitmodules`。
-
-输出要求：
-- `Context:` 当前分支 + 是否存在 `.gitmodules` + submodule 列表
-- `Result:` pull 是否 fast-forward；每个 submodule 是否成功“挂回分支”，失败原因是什么

package/templates/workspace/.opencode/skills/ws-push/SKILL.md

@@ -1,110 +1,18 @@
 ---
 name: ws-push
-description: 推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
+description: Thin wrapper for `aiws push`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-push
 
-目标：
-- 在不自动提交的前提下，安全 push 当前仓库
-- 若仓库包含 submodules：按 `submodules -> superproject` 顺序 push，减少“别人拉取后子模块 detached/分叉”的协作摩擦
-- 若不包含 submodules：按普通 git 仓库的规则 push
+Thin skill wrapper. Delegates to `aiws push`. See `aiws push --help` for details.
 
-安全约束（强制）：
-- 不自动提交、不自动 `git add -A`
-- 不使用 `--force` / `--force-with-lease`
-- 默认只允许 fast-forward push（发现分叉则停止并提示人工处理）
-- 若工作区不干净：停止并要求先 commit 或 stash
-
-执行步骤（建议）：
-0) 输出上下文：
-```bash
-git branch --show-current
-git status --porcelain
-git status -sb
-```
-若 `git status --porcelain` 非空：停止。
-
-1) 判断是否存在 submodules：
 ```bash
-if [[ -f .gitmodules ]]; then
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws push
 else
-  echo "[info] no .gitmodules"
-fi
-```
-
-2) 若不存在 `.gitmodules` 或没有 submodule 条目：按普通仓库 push（仍需用户确认）：
-```bash
-git remote -v
-git push
-```
-
-3) 若存在 submodules：先检查 `.gitmodules` 的 branch 真值是否齐全（缺失则停止并提示 setup）：
-```bash
-missing=0
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-  if [[ -z "${b:-}" ]]; then
-    echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
-    missing=1
-  fi
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-if [[ "$missing" -ne 0 ]]; then
-  echo "hint: run $ws-submodule-setup (and commit .gitmodules), then retry"
-  exit 2
+  npx @aipper/aiws push
 fi
 ```
-
-4) 逐个 push submodules（fast-forward only），再 push superproject：
-```bash
-base_branch="$(git branch --show-current)"
-change_id="$(echo "${base_branch}" | sed -n 's|^change/||p')"
-targets="changes/${change_id}/submodules.targets"
-# Note: if not on a change/ branch, change_id is empty and targets file won't exist;
-# resolution falls back to .gitmodules submodule.<name>.branch via ws_resolve_sub_target.
-
-source tools/ws_resolve_sub_target.sh
-
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-  | while read -r key sub_path; do
-    name="${key#submodule.}"; name="${name%.path}"
-    echo "== submodule: ${sub_path} (${name}) =="
-
-    # submodule 工作区必须干净
-    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
-      echo "error: submodule dirty: ${sub_path}"
-      exit 2
-    fi
-
-    ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
-    target_branch="${_resolved_branch}"
-    remote="${_resolved_remote}"
-
-    git -C "${sub_path}" fetch "${remote}" --prune
-    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
-      echo "error: missing ${remote}/${target_branch} for ${sub_path}"
-      exit 2
-    fi
-
-    # fast-forward only: <remote>/<branch> 必须是 HEAD 的祖先
-    if ! git -C "${sub_path}" merge-base --is-ancestor "${remote}/${target_branch}" HEAD; then
-      echo "error: non-fast-forward (submodule=${sub_path}, remote=${remote}, branch=${target_branch})"
-      echo "hint: rebase/merge in submodule, then retry"
-      exit 2
-    fi
-
-    # push HEAD -> <remote>/<branch>（不 force）
-    git -C "${sub_path}" push "${remote}" "HEAD:refs/heads/${target_branch}"
-  done
-
-# 最后 push superproject（仍需用户确认远端/分支）
-git remote -v
-git push
-```
-
-输出要求：
-- `Context:` 当前分支 + 是否有 submodules
-- `Submodules:` 每个 submodule push 的目标分支与结果（成功/阻断原因）
-- `Superproject:` push 结果

package/templates/workspace/.opencode/skills/ws-quality-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-quality-review
-description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
+description: 使用时机：需要审查实现质量、测试覆盖时。触发词：质量审查、质量、回归、覆盖、代码体检。注意：流程完整性审查请用 ws-spec-review。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
@@ -43,7 +43,12 @@ OpenCode + oMo 优先策略：
    - 行为是否可能回归
    - 边界条件 / 失败路径是否覆盖
    - 测试是否足以支撑改动
-   - 是否存在明显复杂度、耦合、可维护性或性能问题
+    - 是否存在明显复杂度、耦合、可维护性或性能问题
+    - **AI-Slop 检查**（source: `workflow-review-gates.json` aiSlopChecks）：
+      - unnecessary_abstraction：过度抽象（单实现接口、未使用的泛化层）
+      - fake_comments：伪注释（表述代码行为但不解释 why，或与代码不一致）
+      - over_defensive：过度防御（不必要的安全检查、对不可能情况的处理）
+      - cargo_cult：货舱崇拜（照搬模式但不理解原因，如不必要的 observer/strategy）
 3) 将结论落盘到：
    - 默认：`changes/<change-id>/review/quality-review.md`
    - 回退：`.agentdocs/tmp/review/quality-review.md`

package/templates/workspace/.opencode/skills/ws-req-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-req-change
-description: 需求变更（更新 REQUIREMENTS 并同步执行合同）
+description: 使用时机：需要修改需求文档、验收标准时。触发词：需求变更、验收、修改需求、REQUIREMENTS。注意：需求评审未通过请先走 ws-req-review。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

package/templates/workspace/.opencode/skills/ws-req-contract-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-req-contract-sync
-description: 合同同步（requirements contract sync）
+description: 使用时机：需要同步需求执行合同到代码时。触发词：合同同步、contract、req sync。注意：合同内容变更请先 ws-req-change。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。