@aipper/aiws-spec 0.0.21 → 0.0.23

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

@@ -60,6 +60,12 @@ 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
@@ -72,25 +78,25 @@ git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null
       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}"
+    ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
+    target_branch="${_resolved_branch}"
+    remote="${_resolved_remote}"
 
-    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}"
+    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: origin/<branch> 必须是 HEAD 的祖先
-    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})"
+    # 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 -> origin/<branch>（不 force）
-    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
+    # push HEAD -> <remote>/<branch>（不 force）
+    git -C "${sub_path}" push "${remote}" "HEAD:refs/heads/${target_branch}"
   done
 
 # 最后 push superproject（仍需用户确认远端/分支）
@@ -102,4 +108,3 @@ git push
 - `Context:` 当前分支 + 是否有 submodules
 - `Submodules:` 每个 submodule push 的目标分支与结果（成功/阻断原因）
 - `Superproject:` push 结果
-

package/templates/workspace/.claude/commands/{aiws-change-archive.md → p-aiws-change-archive.md}

@@ -3,8 +3,10 @@
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
-- 归档已完成 change 工件
+- 归档已完成 change 工件，并生成交接文档：`changes/archive/.../handoff.md`
 
 执行（在仓库根目录）：
 ```bash

package/templates/workspace/.claude/commands/{aiws-change-finish.md → p-aiws-change-finish.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-finish -->
 # aiws change finish
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-list.md → p-aiws-change-list.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-list -->
 # aiws change list
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-new.md → p-aiws-change-new.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-new -->
 # aiws change new
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-next.md → p-aiws-change-next.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-next -->
 # aiws change next
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-start.md → p-aiws-change-start.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-start -->
 # aiws change start
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-status.md → p-aiws-change-status.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-status -->
 # aiws change status
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-sync.md → p-aiws-change-sync.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-sync -->
 # aiws change sync
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-templates-init.md → p-aiws-change-templates-init.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-templates-init -->
 # aiws change templates init
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-templates-which.md → p-aiws-change-templates-which.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-templates-which -->
 # aiws change templates which
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-validate.md → p-aiws-change-validate.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-validate -->
 # aiws change validate
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-hooks-install.md → p-aiws-hooks-install.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-hooks-install -->
 # aiws hooks install
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-hooks-status.md → p-aiws-hooks-status.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-hooks-status -->
 # aiws hooks status
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-init.md → p-aiws-init.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-init -->
 # aiws init
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
 - 写入/更新 `.gitignore` 的 aiws 托管块
@@ -16,4 +18,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-init -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.claude/commands/{aiws-rollback.md → p-aiws-rollback.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-rollback -->
 # aiws rollback
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 从 `.aiws/backups/` 恢复到某次备份快照
 
@@ -9,4 +11,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-rollback -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.claude/commands/{aiws-update.md → p-aiws-update.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-update -->
 # aiws update
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
 - 更新前备份到 `.aiws/backups/<timestamp>/`
@@ -15,4 +17,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-update -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.claude/commands/{aiws-validate.md → p-aiws-validate.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-validate -->
 # aiws validate
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
 - 强门禁：缺 `python3`/缺 required 脚本也应失败
@@ -10,4 +12,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-validate -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

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

@@ -8,7 +8,10 @@
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
 2) 建立变更归因（推荐）：
-   - 推荐一键：`aiws change start <change-id> --hooks`
+   - ⚠️ 开始前先确认工作区干净：`git status --porcelain` 为空；否则切分支/创建 worktree 后，未提交改动可能“看起来丢了”（worktree 只从 `HEAD` checkout，未提交内容会留在原目录）。
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
+   - 准备进入实现（且工作区干净）后再切换：`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`）

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

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude: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:claude:ws-handoff -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/{aiws-change-archive.md → p-aiws-change-archive.md}

@@ -1,13 +1,15 @@
 ---
-description: 变更归档：归档已完成的 change 工件
+description: 私有：变更归档：归档已完成的 change 工件并生成 handoff.md
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-archive -->
 # aiws change archive
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 归档已完成 change 工件
+- 归档已完成 change 工件，并生成交接文档：`changes/archive/.../handoff.md`
 
 执行（在仓库根目录）：
 ```bash

package/templates/workspace/.opencode/command/{aiws-change-finish.md → p-aiws-change-finish.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更收尾：安全合并 change 分支回目标分支
+description: 私有：变更收尾：安全合并 change 分支回目标分支
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-finish -->
 # aiws change finish
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-list.md → p-aiws-change-list.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更列表：列出当前仓库 change 工件
+description: 私有：变更列表：列出当前仓库 change 工件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-list -->
 # aiws change list
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-new.md → p-aiws-change-new.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更新建：创建 changes/<change-id> 工件
+description: 私有：变更新建：创建 changes/<change-id> 工件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-new -->
 # aiws change new
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-next.md → p-aiws-change-next.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更下一步：输出当前 change 的建议动作
+description: 私有：变更下一步：输出当前 change 的建议动作
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-next -->
 # aiws change next
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-start.md → p-aiws-change-start.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更开始：切到 change/<change-id> 并初始化工件
+description: 私有：变更开始：切到 change/<change-id> 并初始化工件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-start -->
 # aiws change start
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-status.md → p-aiws-change-status.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更状态：查看 change 状态与阻断项
+description: 私有：变更状态：查看 change 状态与阻断项
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-status -->
 # aiws change status
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-sync.md → p-aiws-change-sync.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更同步：同步 change 与真值基线
+description: 私有：变更同步：同步 change 与真值基线
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-sync -->
 # aiws change sync
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-templates-init.md → p-aiws-change-templates-init.md}

@@ -1,9 +1,11 @@
 ---
-description: 模板初始化：初始化 changes/templates 覆盖模板
+description: 私有：模板初始化：初始化 changes/templates 覆盖模板
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-templates-init -->
 # aiws change templates init
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-templates-which.md → p-aiws-change-templates-which.md}

@@ -1,9 +1,11 @@
 ---
-description: 模板来源：查看 change templates 来源
+description: 私有：模板来源：查看 change templates 来源
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-templates-which -->
 # aiws change templates which
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-change-validate.md → p-aiws-change-validate.md}

@@ -1,9 +1,11 @@
 ---
-description: 变更校验：按 strict 校验变更工件与绑定
+description: 私有：变更校验：按 strict 校验变更工件与绑定
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-validate -->
 # aiws change validate
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-hooks-install.md → p-aiws-hooks-install.md}

@@ -1,9 +1,11 @@
 ---
-description: Hooks 启用：启用 git hooks 门禁
+description: 私有：Hooks 启用：启用 git hooks 门禁
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-hooks-install -->
 # aiws hooks install
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-hooks-status.md → p-aiws-hooks-status.md}

@@ -1,9 +1,11 @@
 ---
-description: Hooks 状态：查看当前仓库 hooks 门禁状态
+description: 私有：Hooks 状态：查看当前仓库 hooks 门禁状态
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-hooks-status -->
 # aiws hooks status
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.opencode/command/{aiws-init.md → p-aiws-init.md}

@@ -1,9 +1,11 @@
 ---
-description: 初始化：落盘 AIWS 真值与门禁文件
+description: 私有：初始化：落盘 AIWS 真值与门禁文件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-init -->
 # aiws init
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
 - 写入/更新 `.gitignore` 的 aiws 托管块

package/templates/workspace/.opencode/command/{aiws-rollback.md → p-aiws-rollback.md}

@@ -1,9 +1,11 @@
 ---
-description: 回滚：从 .aiws/backups 恢复快照
+description: 私有：回滚：从 .aiws/backups 恢复快照
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-rollback -->
 # aiws rollback
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 从 `.aiws/backups/` 恢复到某次备份快照
 

package/templates/workspace/.opencode/command/{aiws-update.md → p-aiws-update.md}

@@ -1,9 +1,11 @@
 ---
-description: 更新：刷新模板与 tool-native 文件（先备份）
+description: 私有：更新：刷新模板与 tool-native 文件（先备份）
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-update -->
 # aiws update
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
 - 更新前备份到 `.aiws/backups/<timestamp>/`

package/templates/workspace/.opencode/command/{aiws-validate.md → p-aiws-validate.md}

@@ -1,9 +1,11 @@
 ---
-description: 门禁：校验 required/托管块/漂移（可落盘 stamp）
+description: 私有：门禁：校验 required/托管块/漂移（可落盘 stamp）
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-validate -->
 # aiws validate
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
 - 强门禁：缺 `python3`/缺 required 脚本也应失败

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

@@ -1,5 +1,5 @@
 ---
-description: Commit：门禁/审计后提交（submodule 感知）
+description: 提交：门禁/审计后提交（submodule 感知）
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-commit -->
 # ws commit

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

@@ -11,7 +11,10 @@ description: 开发：在 AIWS 约束下完成小步交付
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
 2) 建立变更归因（推荐）：
-   - 推荐一键：`aiws change start <change-id> --hooks`
+   - ⚠️ 开始前先确认工作区干净：`git status --porcelain` 为空；否则切分支/创建 worktree 后，未提交改动可能“看起来丢了”（worktree 只从 `HEAD` checkout，未提交内容会留在原目录）。
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
+   - 准备进入实现（且工作区干净）后再切换：`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`）

package/templates/workspace/.opencode/command/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/command/ws-review.md

@@ -1,5 +1,5 @@
 ---
-description: Review：提交前审计改动并落盘证据
+description: 评审：提交前审计改动并落盘证据
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-review -->
 # ws review

package/templates/workspace/AGENTS.md

@@ -10,21 +10,24 @@
 - 启用本机门禁（推荐）：`aiws hooks install .`（或手工：`git config core.hooksPath .githooks`；`git commit`/`git push` 会自动跑 `aiws validate .`）
 - 提交前校验（强制门禁）：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - Codex（推荐）：本仓库内置 repo skills：`.agents/skills/`（可显式 `$ws-dev`，也可隐式套用工作流）
+- Codex skills 命名约定：`ws-*` 为常用链路入口；`p-*` 为私有原子入口（一般不需要直接调用）。
 - Codex skills（常用，一句话说明）：
   - `$ws-preflight`：预检（读取真值文件并输出约束摘要）
   - `$ws-submodule-setup`：子模块分支对齐（写入 `.gitmodules` 的 `submodule.<name>.branch`）
   - `$ws-plan`：规划（生成可落盘 `plan/` 工件；供 `$ws-dev` 执行）
   - `$ws-plan-verify`：计划质检（执行前检查计划是否过长/跑偏）
+  - `$p-tasks-plan`：原子：tasks 同步（从 `changes/<id>/tasks.md` 生成 `update_plan` payload）
   - `$ws-dev`：开发（按需求实现并验证；适用于任何需要修改代码/配置的任务）
   - `$ws-bugfix`：缺陷修复（禅道 MCP 拉单 + 图片证据落盘 + `issues/fix_bus_issues.csv` 汇总）
   - `$ws-pull`：拉取并对齐 submodules（尽量避免 detached；减少人为差异）
   - `$ws-push`：推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
   - `$ws-review`：评审（提交前审计；证据优先落盘到 `changes/<change-id>/review/`）
   - `$ws-commit`：提交（先审计/门禁再 commit；submodule 感知）
-  - `$aiws-init`：初始化工作区（生成真值文件与门禁）
-  - `$aiws-validate`：校验工作区（漂移检测 + 门禁）
-  - `$aiws-hooks-install`：启用 git hooks 门禁（`core.hooksPath=.githooks`）
-  - `$aiws-change-new`：创建 `changes/<change-id>` 工件
+  - `$ws-handoff`：交接（归档后生成/查看 `changes/archive/.../handoff.md`，便于跨会话接力）
+  - `$p-aiws-init`：初始化工作区（生成真值文件与门禁）
+  - `$p-aiws-validate`：校验工作区（漂移检测 + 门禁）
+  - `$p-aiws-hooks-install`：启用 git hooks 门禁（`core.hooksPath=.githooks`）
+  - `$p-aiws-change-new`：创建 `changes/<change-id>` 工件
 - Codex CLI（推荐，可选）：安装全局 skills：`npx @aipper/aiws codex install-skills`（写入 `~/.codex/skills/` 或 `$CODEX_HOME/skills`）
 - Codex CLI（遗留，可选）：安装全局 prompts：`npx @aipper/aiws codex install-prompts`（写入 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`；prompts 已 deprecated）
 - 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等