@aipper/aiws-spec 0.0.24 → 0.0.26

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

@@ -0,0 +1,54 @@
+---
+name: ws-migrate
+description: 迁移（补齐/升级 AIWS 工作区文件）
+---
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+
+执行（在项目根目录）：
+```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
+elif command -v aiws >/dev/null 2>&1; then
+  aiws rollback . latest
+else
+  npx @aipper/aiws rollback . latest
+fi
+```
+
+约束：
+- 不写入任何 secrets。
+- 不执行破坏性命令。

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

@@ -0,0 +1,148 @@
+---
+name: ws-plan
+description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 对齐真值文件（`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）
+- 若尚未进入本次 change 的工作上下文：先建立 `change/<change-id>` 分支 / worktree，再生成计划
+- 为当前任务生成一份可追踪的执行计划文件：`plan/<timestamp>-<slug>.md`
+- 计划必须包含可复现验证命令（优先引用 `AI_WORKSPACE.md`）
+- 计划必须包含“主索引绑定”：`Change_ID` / (`Req_ID` or `Problem_ID`) / `Contract_Row` / `Plan_File` / `Evidence_Path`
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `planner-sisyphus` / `explore` / `librarian`，优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+- 计划主框架优先交给 `planner-sisyphus`；代码结构探索优先交给 `@explore`；规范/文档/依赖查证优先交给 `@librarian`。
+- 主 agent 负责回收这些结果并最终落盘 `plan/...`；不要把“调用了 oMo agent”当作已经完成计划。
+
+约束：
+- 不写入任何 secrets（token、账号、内网端点等不得进入 git）
+- 本 skill 只负责“想清楚怎么做 + 落盘计划”，不要直接大规模改动代码
+- 未运行不声称已运行；验证命令要写清“预期结果”
+- 若存在 `changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
+
+阶段定位：
+- planning 阶段；负责把用户目标收敛为 change 绑定、计划文件和验证入口。
+
+必需输入：
+- 当前任务描述
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 若已存在：`changes/<change-id>/proposal.md`
+- 若已有计划：当前 `plan/...` 文件
+
+必需输出：
+- `Plan file:` 实际写入的 `plan/...`
+- `Change context:` 当前生效的 `change/<change-id>` 分支或 worktree
+- `Bindings:` `Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
+- `Verify:` 可复现验证命令与预期
+- `Next:` 先 `$ws-plan-verify`，通过后再 `$ws-dev`
+
+阻断条件：
+- 任务目标或归因绑定不清晰
+- 当前工作区 dirty 且尚未进入可复用的 change 上下文
+- 无法把计划实际写盘
+
+完成判定：
+- 计划已落盘、绑定已同步、验证入口明确，后续实现可以直接按计划推进。
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
+   - 若检测到 oMo：优先让 `planner-sisyphus` 生成 planning draft；若需要补结构探索，再委托 `@explore` / `@librarian`。
+2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
+3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
+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/...` 写回原工作区
+5) 生成计划文件：
+   - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
+   - 若 `plan/` 不存在先创建
+   - 必须实际写入到磁盘（不要只在对话里输出）；如因权限/策略无法写盘，必须明确说明原因并输出可复制的完整内容
+   - 计划必须写在当前 active change 上下文内：若当前已进入 `change/<change-id>` worktree，则 `plan/...`、`proposal.md`、`tasks.md` 都应写在该 worktree 中
+6) 计划内容至少包含（不要留空）：
+   - `Bindings`：`Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
+   - `Goal`：要达成什么
+   - `Non-goals`：明确不做什么（避免 scope creep）
+   - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
+   - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
+   - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
+   - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
+   - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
+   - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
+7) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
+8) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
+9) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
+10) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
+
+oMo 回退：
+- 若当前没有 oMo、没有 `planner-sisyphus`，或你无法稳定调用相关 agent：直接回退为普通 OpenCode `plan` / 当前 agent 本地规划。
+- 回退不改变 AIWS 的要求：`plan/...` 仍必须落盘，bindings / verify / risks / evidence 仍必须完整。
+
+补充：submodule 目标分支真值（强约束；同一 superproject 分支内可多渠道）
+- 背景：`.gitmodules submodule.<name>.branch` 适合作为“团队默认分支真值”，但当同一 superproject 分支需要在不同交付中选择不同 submodule 目标分支（多渠道）时，仅靠 `.gitmodules` 不足。
+- 强约束：当 `.gitmodules` 声明了 submodule 条目时，门禁会要求本次 change 存在该文件且覆盖所有 submodule path（否则 `aiws validate .` / `aiws change validate --strict` 阻断）。
+- 约定：为本次 change 落盘一个“交付目标分支映射”文件，并在后续 `$ws-dev`/`$ws-deliver`/`$ws-finish` 优先使用它：
+  - 文件：`changes/<change-id>/submodules.targets`
+  - 格式：每行一个 submodule（忽略空行与 `#` 注释），字段用空白分隔（推荐 `TAB`）：
+    - 第 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}"
+```
+- 计划里必须写清：本次交付选择的 `targets` 内容，以及后续在 `$ws-dev` 进入编码前会把 submodules 挂到 `aiws/pin/<target_branch>`（必要时先 `fetch`）。
+
+输出要求：
+- `Plan file:` <实际写入的路径>
+- `Change context:` <当前 change 分支或 worktree 路径；若新建了 worktree 需明确写出>
+- `Next:` 推荐下一步（先 `$ws-plan-verify`，通过后再 `$ws-dev`；或 `aiws change start <change-id> --hooks`，superproject + submodule 可用 `--worktree`）

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

@@ -0,0 +1,61 @@
+---
+name: ws-plan-verify
+description: 计划质检（执行前检查计划是否过长/跑偏，并给出最小修正清单）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在进入 `$ws-dev` 前，对 `plan/...` 与 `changes/<change-id>/proposal.md` 做一次“硬约束”质检
+- 避免计划过长、步骤不够具体、验证不可复现、与需求合同绑定不一致
+- 失败时只给最小修正项，修完后再进入实现
+
+适用时机：
+- 已执行过 `$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
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate <change-id> --strict
+else
+  npx @aipper/aiws change validate <change-id> --strict
+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

@@ -0,0 +1,60 @@
+---
+name: ws-preflight
+description: 预检（提交前快速检查与建议）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
+
+阶段定位：
+- workflow 入口阶段；负责判断当前仓库是否具备继续执行其它 `ws-*` 阶段的前置条件。
+
+必需输入：
+- 当前项目根目录候选路径
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Missing:` 缺失项
+- `OpenCode mode:` `oMo-enabled` / `standard-opencode`
+- `Key rules:` 3-8 条约束摘要
+- `Next:` 若真值齐全，建议进入 `$ws-plan` 或 `$ws-dev`；若缺失，建议先 `aiws init .`
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+
+完成判定：
+- 使用者已经知道当前仓库能否继续进入后续阶段，以及必须遵守的约束与下一步入口。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 若缺失任意真值文件：不要继续“写代码/改配置/落盘文件”。先输出缺失项，并给出下一步建议：
+   - `npx @aipper/aiws init .`（或 `aiws init .`）初始化真值文件
+   - 然后重新执行 `$ws-preflight`
+4) 输出：
+   - `Root:` <项目根路径>
+   - `Found:` <实际读取到的文件列表>
+   - `Missing:` <缺失文件列表>
+   - `OpenCode mode:` 
+     - 若检测到 `.opencode/oh-my-opencode.json`：`oMo-enabled`
+     - 否则：`standard-opencode`
+   - 若为 `oMo-enabled`：附一句说明后续 `ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 会优先借用 oMo agent
+   - `Key rules:` 3–8 条 bullet（范围/禁止项/必须产物/必须验证命令）
+5) 若存在 `.gitmodules`：
+   - 输出 submodule 列表：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 检查每个 submodule 是否配置 `submodule.<name>.branch`（缺失则提示先运行 `$ws-submodule-setup`；否则 `aiws validate .` 会失败）
+
+安全：
+- 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。
+- 不执行破坏性命令。

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

@@ -0,0 +1,119 @@
+---
+name: ws-pull
+description: 拉取并对齐 submodules（避免 detached；减少人为差异）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+背景：
+- Git submodule 在别的电脑 `git submodule update` 后常见现象是子模块处于 detached HEAD（因为主仓库记录的是固定 gitlink commit）。
+- detached 本身不一定是错，但会增加“需要手动切分支/容易忘”的操作差异。
+
+目标：
+- 安全拉取 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
+else
+  echo "[info] no .gitmodules"
+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

@@ -0,0 +1,110 @@
+---
+name: ws-push
+description: 推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在不自动提交的前提下，安全 push 当前仓库
+- 若仓库包含 submodules：按 `submodules -> superproject` 顺序 push，减少“别人拉取后子模块 detached/分叉”的协作摩擦
+- 若不包含 submodules：按普通 git 仓库的规则 push
+
+安全约束（强制）：
+- 不自动提交、不自动 `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
+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
+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

@@ -0,0 +1,63 @@
+---
+name: ws-quality-review
+description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动的行为正确性、边界条件、测试覆盖和实现质量
+- 把“代码/行为层 findings”优先落盘到 `changes/<change-id>/review/quality-review.md`
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore`，优先借用这些 agent 做质量审查。
+- `@oracle` 优先负责独立质量/回归审查；`@explore` 负责补代码路径、依赖关系和影响面探索。
+- 主 agent 负责把 findings / gaps / next 收敛并落盘。
+
+阶段定位：
+- review 子 gate；负责实现质量、行为回归与验证覆盖审查。
+
+必需输入：
+- 当前 `git diff`
+- 已执行的验证结果
+- 相关代码 / 配置 / 测试文件
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 review 文件
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/quality-review.md` 或回退 `.agentdocs/tmp/review/quality-review.md`
+- `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
+- `下一步（Next）:` 最小修复项与回归命令
+
+阻断条件：
+- 没有可审改动
+- 没有任何验证上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 quality review 证据，且 findings / 测试缺口 / next 明确。
+
+步骤（建议）：
+1) 先读取 `git diff`、验证结果与相关代码。
+   - 若检测到 oMo：优先让 `@oracle` 做 quality review 草稿；必要时再调用 `@explore` 补代码路径上下文。
+2) 检查：
+   - 行为是否可能回归
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑改动
+   - 是否存在明显复杂度、耦合、可维护性或性能问题
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是质量 / 回归 review，不替代 requirements / gate review。
+- 若发现流程、归因、evidence 缺口，转交给 `$ws-spec-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+- 若 oMo agent 不可用，回退为当前 agent 本地 quality review。

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

@@ -0,0 +1,41 @@
+---
+name: ws-req-change
+description: 需求变更（更新 REQUIREMENTS 并同步执行合同）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `REQUIREMENTS.md` + 追加 `requirements/CHANGELOG.md`），并同步/校验执行合同 `requirements/requirements-issues.csv`。
+
+步骤（必须按顺序）：
+1) 读取：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`requirements/CHANGELOG.md`（缺失则创建目录与文件）。
+2) 先产出“拟变更方案”（不要立刻写文件）：
+   - 变更摘要（1–5 条）
+   - 影响范围（API/鉴权/字段/状态码/测试边界）
+   - 回滚思路（1–2 条）
+3) 对比与冲突检查（强制，不写文件）：
+   - 对比“变更前 vs 拟变更后”的差异清单（新增/删除/语义变化）
+   - 整理潜在冲突/不确定点（只列“最可能影响验收/实现”的，避免噪音）
+4) 逐条澄清（强制，避免一次问完）：
+   - 若存在潜在冲突/不确定点：**本轮只问 1 个**最高优先级问题（给出 2–4 个可选答案或二选一），然后停止，等待用户回复；不要继续问下一题，也不要写文件。
+   - 收到用户回复后：更新“拟变更方案”，回到步骤 3) 重新对比，直至没有未决问题。
+5) 强制停下来让用户确认：是否继续落盘？(Y/N)
+6) 用户确认 Y 后再写入：
+   - 更新 `REQUIREMENTS.md`（只保留当前有效版本，不在此堆历史）
+   - 追加 `requirements/CHANGELOG.md`
+7) 同步/补齐需求执行合同（强制，自动处理 FlowSpec 有/无两种情况）：
+   - `python3 tools/requirements_contract_sync.py --workspace .`
+   - 说明：若 `REQUIREMENTS.md` 中不存在 FlowSpec（或 flows 为空），该命令只会确保 `requirements/requirements-issues.csv` 表头存在并给出 WARN（这是预期行为，不要当成失败）。
+8) 校验需求执行合同（强制）：`python3 tools/requirements_contract.py validate`
+9) 同步场景合同（可选，但若存在 FlowSpec 则强烈建议自动执行）：
+   - 若 `REQUIREMENTS.md` 同时包含 `<!-- FLOW_SPEC_BEGIN -->` 与 `<!-- FLOW_SPEC_END -->`：运行 `$ws-req-flow-sync`
+   - 否则：跳过，并提示用户“可以先不维护 FlowSpec；后续需要场景回归时再补”
+
+输出必须包含：
+- 本次更新的文件清单（路径）
+- 回滚方案（如何撤销本次需求变更）
+- 下一步建议命令
+
+安全：
+- 不打印 `secrets/test-accounts.json`
+- 不引入任何 token/密钥到仓库