@aipper/aiws-spec 0.0.23 → 0.0.25

package/templates/workspace/.opencode/commands/ws-commit.md

@@ -0,0 +1,70 @@
+---
+description: 提交：门禁/审计后提交（submodule 感知）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-commit -->
+# ws commit
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在**当前分支可直提**的前提下，先做审计与门禁，并在存在 submodule 时给出正确的提交顺序（先 submodule，再 superproject），最后执行 `git commit`。
+补充：若你经常遇到 submodule detached，建议日常拉取优先使用 `/ws-pull`（尽量把 submodule “挂回分支”且不改变 gitlink commit）。
+
+安全约束（强制）：
+- 不自动 `git add -A`；只在用户明确指示时才做 staging
+- 不使用 `--no-verify` 绕过 hooks
+- 不自动 push
+- 不打印 secrets
+- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 运行 `/ws-review`（优先落盘审计证据到 `changes/<change-id>/review/`）。
+3) 运行门禁校验并写 stamp：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws validate . --stamp
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate . --stamp
+else
+  npx @aipper/aiws validate . --stamp
+fi
+```
+4) 输出提交上下文（必须输出给用户确认）：
+```bash
+git branch --show-current
+git status --porcelain
+```
+5) submodule 感知检查：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+fi
+while read -r _ sub_path; do
+  [[ -z "${sub_path:-}" ]] && continue
+  echo "== submodule: ${sub_path} =="
+  git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
+  git -C "${sub_path}" status --porcelain || true
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+```
+判定规则（强制）：
+- 任一 submodule `git status --porcelain` 非空：停止提交 superproject；先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`。
+6) 检查 staging（必须输出给用户确认）：
+```bash
+git status --porcelain
+git diff --staged --submodule=short
+```
+7) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
+8) 优先生成并确认中文 commit message（格式建议：`<类型>: <简述>`；若用户明确要求英文也可保留，但 strict 模式下会被 hook 拒绝）。
+9) 执行提交（不带 `--no-verify`）：
+```bash
+git commit -m "<message>"
+```
+
+输出必须包含：
+- `证据（Evidence）:` `changes/<change-id>/review/*`（无 change-id 时回退 `.agentdocs/tmp/review/*`） + `.agentdocs/tmp/aiws-validate/*`
+- `上下文（Context）:` 当前分支 + 是否检测到 submodule + 若阻断则给出阻断原因
+- `下一步（Next）:` 若存在 submodule 改动，先提示用户进入 submodule 提交
+<!-- AIWS_MANAGED_END:opencode:ws-commit -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-delegate.md

@@ -0,0 +1,33 @@
+---
+description: 委托：按 AIWS 合同拆分子任务，并优先借用 oMo agent
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-delegate -->
+# ws delegate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：先写清 delegation plan，再决定是否优先借用 `oh-my-opencode` 的 `planner-sisyphus` / `explore` / `librarian` / `oracle`；若不可用则回退，不阻断流程。
+
+执行建议：
+1) 先运行 `/ws-preflight`，再读取 `packages/spec/docs/workflow-delegation-contracts.md` 与 `packages/spec/docs/opencode-omo-adapter.md`。
+2) 先写 `Delegation Plan:`，至少包含：
+   - `role`
+   - `preferred agent`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+3) 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用相关 agent：
+   - planning 优先 `planner-sisyphus`
+   - 探索优先 `@explore` / `@librarian`
+   - 独立审查优先 `@oracle`
+4) 主 agent 统一收敛结果，并把产物回收到：
+   - `changes/<id>/analysis/`
+   - `changes/<id>/patches/`
+   - `changes/<id>/review/`
+   - `changes/<id>/evidence/`
+5) 若 oMo agent 不可用：明确回退为普通 OpenCode delegation / 单 agent 执行。
+<!-- AIWS_MANAGED_END:opencode:ws-delegate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-deliver.md

@@ -0,0 +1,58 @@
+---
+description: 交付：submodules+superproject 分步提交并安全合并回 base
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-deliver -->
+# ws deliver
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：适配 superproject + submodule（数量不固定）的交付收尾，降低提交顺序和合并回 base 分支的出错概率：
+1) 先逐个提交 submodule（每个 repo 单独确认 commit message；默认 `git add -p`）
+2) 再提交 superproject（包含 submodule gitlink 指针更新 + 自身改动/变更工件）
+3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `/ws-finish`）
+
+强制约束：
+- 不自动 `git add -A`。
+- 不自动 push。
+- 不自动删除分支。
+
+建议流程（按顺序）：
+1) 先运行 `/ws-preflight`。
+2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `/ws-submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
+2.1) 若存在 submodule：必须准备 `changes/<change-id>/submodules.targets`，并覆盖所有 submodule path；这是本次交付的目标分支真值。
+   - 生成该文件时可先做默认预填：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在本地分支时默认建议取当前分支。
+   - 上述都只是建议值；真正的 deliver/finish 只认 `submodules.targets`。
+2) 发现 submodules：
+   - `git submodule status --recursive`
+3) 逐个提交 submodules（按上一步顺序）：
+   - `git -C "<sub_path>" status --porcelain`
+   - 先说明该 submodule 目标分支的来源：attached branch 默认建议取当前分支；detached HEAD 默认建议取 `.gitmodules`；若与 `submodules.targets` 已落盘值冲突，则以 `submodules.targets` 为准
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `submodules.targets`（若分支为 `.` 则展开为 `.ws-change.json` 的 `base_branch`）挂到 `aiws/pin/<target-branch>`
+   - `git -C "<sub_path>" add -p`
+   - `git -C "<sub_path>" diff --staged --stat`
+   - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）
+   - `git -C "<sub_path>" commit -m "<message>"`
+4) 提交 superproject（gitlinks + 自身改动）：
+   - `git diff --submodule`
+   - `git add <submodule-path-1> <submodule-path-2> ...`
+   - `git add -p`
+   - 生成并让用户确认 superproject 的 commit message
+   - `git commit -m "<message>"`
+5) （推荐）门禁 + 证据：
+   - `aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）
+5.1) （强烈建议）生成持久证据并回填 `Evidence_Path`：
+   - `aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）
+5.2) （可选）生成状态快照（建议）：
+   - `aiws change state <change-id> --write`
+6) 安全合并回目标分支：
+   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
+
+输出要求：
+- `Submodules:` 每个 submodule 的 commit 摘要（repo/path → sha → message）
+- `Superproject:` commit 摘要
+- `Merge:` `/ws-finish` 输出（into/from）
+- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
+- `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
+<!-- AIWS_MANAGED_END:opencode:ws-deliver -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-dev.md

@@ -0,0 +1,36 @@
+---
+description: 开发：在 AIWS 约束下完成小步交付
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-dev -->
+# ws dev
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+建议流程：
+1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `/ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
+2) 建立变更归因（推荐）：
+   - ⚠️ 若准备切分支/创建 worktree，先看 `git status --porcelain`；否则切换上下文后，未提交改动可能“看起来丢了”。
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `/ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若非空仅因为 `/ws-plan` 生成了 `plan/...` 或 `changes/<change-id>/...`，这是预期行为；此时优先 `aiws change start <change-id> --hooks --no-switch`，若仍要 `--switch/--worktree`，先提交这些规划工件。
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
+   - 准备进入实现时：若当前已在 `change/<change-id>` 直接继续；若需切换到该分支，先确认除规划工件外无额外未提交改动，再执行：`git switch change/<change-id>`
+   - 若你明确要“一键切分支”（不推荐，且 dirty 会被拦截）：`aiws change start <change-id> --hooks --switch`
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 或手工：`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) 提交前强制：`aiws validate .`（commit/push hooks 也会阻断）。
+7) 交付收尾（推荐，减少手动 merge 出错）：运行 `/ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
+
+输出要求：
+- `变更文件（Changed）:` 文件清单
+- `验证（Verify）:` 实际运行的命令 + 期望结果
+- `证据（Evidence）:` 证据路径（例如 `changes/<change-id>/review/...`、`changes/<change-id>/...` 或 `.agentdocs/tmp/...`）
+<!-- AIWS_MANAGED_END:opencode:ws-dev -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-finish.md

@@ -0,0 +1,71 @@
+---
+description: 收尾：fast-forward 合并并把 submodule 并回目标分支后顺序 push
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-finish -->
+# ws finish
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，避免手输分支名导致的错误。
+补充：若团队希望减少 submodule detached 的人为差异，建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `/ws-pull`。
+
+前置（必须）：
+- 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
+- change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+ - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
+
+步骤（建议）：
+0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
+```bash
+if [[ -f .gitmodules ]]; then
+  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
+fi
+```
+1) 先运行 `/ws-preflight`（确保真值文件齐全）。
+2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+2.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
+2.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
+3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+   - `aiws change finish <change-id> --push`
+   - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`
+   - 该命令会在 fast-forward 合并成功后 push 目标分支；默认优先使用 upstream 配置（`branch.<name>.remote` + `branch.<name>.merge`），只有在你明确知道要推向别的 remote 时才追加 `--remote <name>`
+   - 若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则会在 push 成功后自动执行 `git worktree remove` + `git worktree prune`
+   - AI 入口执行前，应先向用户说明将要 push 的 remote/branch；显式传入 `--push` 即视为确认
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若需要先处理 submodules，则按顺序处理每个 submodule（减少 detached；再 push）：
+   - 先显式解析 base branch，不要用当前分支名替代：
+     - `python3 - <<'PY'`
+     - `import json, pathlib; meta = pathlib.Path("changes") / "<change-id>" / ".ws-change.json"; print((json.loads(meta.read_text(encoding="utf-8")).get("base_branch") or "").strip())`
+     - `PY`
+   - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 对每个 `<sub_path>`：
+     - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
+     - 目标分支真值：`changes/<change-id>/submodules.targets`；若条目里分支写 `.`，则展开为刚才解析出的 `base_branch`
+     - 生成/检查 `submodules.targets` 时，detached HEAD 默认建议取 `.gitmodules` 的 `submodule.<name>.branch`；已附着在本地分支时默认建议取当前分支；这些都只是预填建议，不是 finish/push 的运行时真值
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached
+     - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
+     - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
+     - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
+6) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
+7) submodules 全部成功后，再回到主仓库执行：
+   - `aiws change finish <change-id> --push`
+8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+
+安全：
+- push 前先输出状态并说明远端/分支。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-finish -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-handoff.md

@@ -0,0 +1,25 @@
+---
+description: 交接：查看归档 change 的 handoff.md（由 aiws change archive 生成）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-handoff -->
+# ws handoff
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 交接与回放：通过 `handoff.md` 让已归档的 change 可被下一位/下一次会话快速接力。
+- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（由 `aiws change archive` 自动生成）。
+
+执行建议：
+1) 若 change 已完成并准备归档：运行 `/p-aiws-change-archive`（会先严格校验，再归档并生成 `handoff.md`）。
+2) 查看 handoff：
+```bash
+change_id="<change-id>"
+ls -1 changes/archive/*-"${change_id}"/handoff.md
+sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
+```
+3) 依赖提示：
+- 若你在某个 change 的 `proposal.md` 声明了 `Depends_On`，`aiws change start` 会尝试读取依赖 change 的 `handoff.md` 并输出摘要（前提：依赖已归档且 handoff 存在）。
+<!-- AIWS_MANAGED_END:opencode:ws-handoff -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-migrate.md

@@ -0,0 +1,25 @@
+---
+description: 迁移：把仓库对齐到 aiws workspace 模板
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-migrate -->
+# ws migrate
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+
+执行（在项目根目录）：
+1) 若已存在 `.aiws/manifest.json`：`npx @aipper/aiws update .`
+2) 否则：`npx @aipper/aiws init .`
+3) 门禁校验：`npx @aipper/aiws validate .`
+4) 启用本机 git hooks（推荐，本地生效）：`git config core.hooksPath .githooks`
+
+回滚：
+- 恢复最近一次快照：`npx @aipper/aiws rollback . latest`
+
+约束：
+- 不写入任何 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-migrate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-plan-verify.md

@@ -0,0 +1,28 @@
+---
+description: 计划质检：执行前检查并给出最小修正项
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-plan-verify -->
+# ws plan verify
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 执行前检查计划是否跑偏，并给出最小修正项。
+
+执行建议：
+1) 先运行 `/ws-preflight`。
+2) 运行严格门禁：
+```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
+```
+3) 若失败：先修 `proposal.md` / `plan` 的绑定字段与验证命令，再复跑。
+4) 通过后再进入 `/ws-dev`。
+<!-- AIWS_MANAGED_END:opencode:ws-plan-verify -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-plan.md

@@ -0,0 +1,27 @@
+---
+description: 规划：生成可落盘 plan 工件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-plan -->
+# ws plan
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 若尚未进入本次 change 的工作上下文：先建立 `change/<change-id>` 分支 / worktree，再生成可落盘执行计划（供 /ws-dev 执行）。
+
+执行建议：
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `planner-sisyphus` / `explore` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - 计划主框架优先 `planner-sisyphus`；结构探索优先 `@explore`；规范/文档查证优先 `@librarian`。
+2) 若当前不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start <change-id>` 建立上下文：
+   - 仓库已有提交：优先 `aiws change start <change-id> --hooks --worktree`；若声明了 submodules，加 `--submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `aiws change start <change-id> --hooks --no-switch`
+3) 若上一步创建了 worktree：切到输出的 `worktree:` 路径，后续所有计划文件都写在该 worktree 中。
+4) 生成或更新计划文件：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`。
+5) 计划至少包含：`Bindings`、`Goal`、`Non-goals`、`Scope`、`Plan`、`Verify`、`Risks & Rollback`、`Evidence`。
+6) 若已有 `changes/<change-id>/proposal.md`，对齐 `Plan_File` / `Contract_Row` / `Evidence_Path`。
+7) 完成后先运行 `/ws-plan-verify`，通过再进入 `/ws-dev`。
+8) 若 oMo 不可用：回退为普通 OpenCode `plan` / 当前 agent 本地规划，但仍必须落盘完整 `plan/...`。
+<!-- AIWS_MANAGED_END:opencode:ws-plan -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-preflight.md

@@ -0,0 +1,34 @@
+---
+description: 预检：读取真值文件并输出约束摘要
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-preflight -->
+# ws preflight
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 输出：
+   - `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（范围/禁止项/必须产物/必须验证命令）
+
+安全：
+- 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-preflight -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-pull.md

@@ -0,0 +1,87 @@
+---
+description: 拉取：fast-forward 拉取并对齐 submodules（尽量避免 detached）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-pull -->
+# ws pull
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全拉取 superproject，并对齐 submodules，尽量把 submodule 从 detached HEAD “挂回”分支（仅当该分支包含 gitlink commit），减少人为操作差异。
+
+安全约束（强制）：
+- 不执行破坏性命令；不自动提交/不自动 push
+- 若工作区不干净：停止并要求用户先 commit 或 stash
+- `git pull` 默认只允许 fast-forward（避免隐式 merge/rebase）
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+```bash
+git rev-parse --show-toplevel
+git branch --show-current
+git status --porcelain
+```
+若 `git status --porcelain` 非空：停止。
+
+2) 拉取 superproject（fast-forward only）：
+```bash
+git pull --ff-only
+```
+若失败：停止并说明需要用户明确选择 `git pull --rebase` 或手动处理。
+
+3) 更新 submodules 到 superproject 记录的 gitlink commit：
+```bash
+if [[ -f .gitmodules ]]; then
+  git submodule sync --recursive
+  git submodule update --init --recursive
+else
+  echo "[info] no .gitmodules"
+fi
+```
+
+4) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”（不改动 gitlink commit）：
+为避免 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)"
+      [[ -z "${sub_sha:-}" ]] && { echo "[warn] no gitlink sha"; continue; }
+
+      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)"
+        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
+          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
+    done
+fi
+```
+
+可选（方案 2，一次性设置 submodule 跟踪分支，会改 `.gitmodules`，需提交）：
+```bash
+git submodule set-branch --branch main <sub_path>
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branch"
+```
+<!-- AIWS_MANAGED_END:opencode:ws-pull -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-push.md

@@ -0,0 +1,93 @@
+---
+description: 推送：submodule 感知（先 submodules 后 superproject；fast-forward；不 force）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-push -->
+# ws push
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全 push 当前仓库；若仓库包含 submodules，则先 push submodules，再 push superproject（默认 fast-forward；不 force）。
+
+强制约束：
+- 不自动提交、不自动 `git add -A`
+- 不使用 `--force` / `--force-with-lease`
+- 若工作区不干净：停止并要求先 commit 或 stash
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+```bash
+git branch --show-current
+git status --porcelain
+git status -sb
+```
+若 `git status --porcelain` 非空：停止。
+
+2) 判断是否存在 submodules：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+fi
+```
+
+3) 若没有 submodules：正常 push（仍需用户确认远端/分支）：
+```bash
+git remote -v
+git push
+```
+
+4) 若有 submodules：先检查 `.gitmodules` 的 `submodule.<name>.branch` 是否齐全（缺失则停止并提示 `/ws-submodule-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
+```
+
+5) 逐个 push submodules（fast-forward only），再 push superproject：
+```bash
+base_branch="$(git branch --show-current)"
+
+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}) =="
+
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
+      echo "error: submodule dirty: ${sub_path}"
+      exit 2
+    fi
+
+    cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+    if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
+    target_branch="${cfg_branch}"
+
+    git -C "${sub_path}" fetch origin --prune
+    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
+      echo "error: missing origin/${target_branch} for ${sub_path}"
+      exit 2
+    fi
+
+    if ! git -C "${sub_path}" merge-base --is-ancestor "origin/${target_branch}" HEAD; then
+      echo "error: non-fast-forward (submodule=${sub_path}, branch=${target_branch})"
+      exit 2
+    fi
+
+    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
+  done
+
+git remote -v
+git push
+```
+<!-- AIWS_MANAGED_END:opencode:ws-push -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/.opencode/commands/ws-quality-review.md

@@ -0,0 +1,30 @@
+---
+description: 质量审查：行为回归 / 测试覆盖 / 实现质量
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-quality-review -->
+# ws quality review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查行为回归、边界条件、测试覆盖与实现质量。
+
+步骤（建议）：
+1) 读取 `git diff`、已执行的验证结果和相关代码。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `explore`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - 质量/回归审查优先 `@oracle`；代码路径与影响面补充优先 `@explore`。
+2) 检查：
+   - 是否存在行为回归或明显 bug 风险
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑当前改动
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+5) 若 oMo 不可用：回退为当前 agent 本地 quality review。
+<!-- AIWS_MANAGED_END:opencode:ws-quality-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。