@aipper/aiws-spec 0.0.24 → 0.0.26

package/templates/workspace/.claude/skills/ws-dev-lite/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ws-dev-lite
+description: 轻量开发（simple/local 单点修复；最小改动 + 最小验证）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不引入完整重流程的前提下，完成一次 simple/local 小问题修复，并保持可验证、可追溯。
+
+定位：
+- `ws-dev` 的轻量入口，不是新的 workflow stage。
+- 适用于单点修复、局部配置调整、明确回归修复；不适用于中大型任务。
+
+适用前提：
+- 目标明确，且能归因到 `Req_ID` 或 `Problem_ID`
+- 验证入口明确，且能做最小可复现验证
+- 一般只影响单文件或紧密相关的小范围文件
+- 不需要先改 `REQUIREMENTS.md`，也不需要先单独做 review
+
+立即升级回主流程的情形：
+- 发现任务其实是 medium/complex、跨模块、跨目录或需要方案设计
+- 无法明确归因、verify、change 上下文
+- 需要新建复杂 change/worktree 或处理 submodule 目标分支真值
+- 修复过程中出现连锁改动、需要补系统性测试或需求调整
+
+默认约束：
+- 先做 `$ws-preflight`
+- 默认不创建 `plan/...`
+- 默认不跑 `$ws-plan-verify`
+- 默认不要求先做双 review
+- 若后续准备提交/交付，仍需进入 `$ws-review` / `$ws-commit` / `$ws-finish`
+
+执行步骤：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+2) 先判断自己是否真的属于 lite：
+   - 用一句话写清 `Goal`
+   - 用一句话写清 `Why lite`
+   - 若说不清，立刻回退到 `$ws-dev` 或 `$ws-plan`
+3) 在当前 change 上下文内实施最小改动：
+   - 不为“形式完整”额外扩 scope
+   - 不默认补与本问题无关的重构或测试矩阵
+4) 运行最小可复现验证：
+   - 优先使用 `AI_WORKSPACE.md` 已声明的命令
+   - 若只需局部回归，允许运行更窄的验证，但要说明为什么足够
+5) 留下至少一个可追溯证据：
+   - 实际改动文件
+   - 或 `.agentdocs/tmp/...`
+   - 或 `changes/<change-id>/...`
+6) 输出：
+   - `变更文件（Changed）:`
+   - `验证（Verify）:`
+   - `证据（Evidence）:`
+   - `Next:` 若准备提交，进入 `$ws-review` 或 `$ws-commit`
+
+输出要求：
+- 明确说明为什么这是 lite，而不是完整 `ws-dev`
+- 未运行不声称已运行
+- 一旦发现复杂度升高，立刻停止 lite 叙事，切回 `$ws-dev` 或 `$ws-plan`

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

@@ -0,0 +1,209 @@
+---
+name: ws-finish
+description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在结束一次变更交付时，用 fast-forward 安全合并 `change/<change-id>` 回目标分支，减少手输分支名导致的错误
+- 合并成功后，按 `submodule -> superproject` 顺序 push，避免遗漏导致其它仓库拉取异常
+- 不自动删分支；AI 入口执行前应先向用户说明将要 push 的 remote/branch，显式传入 `--push` 即视为确认
+- 若团队希望减少 submodule detached 的人为差异：建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `$ws-pull`
+
+前置（必须）：
+- 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
+- change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
+- 若使用 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
+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) （推荐）先跑一次门禁并落盘证据：
+```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
+```
+1.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change evidence "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change evidence "${change_id}"
+else
+  npx @aipper/aiws change evidence "${change_id}"
+fi
+```
+1.2) （可选）生成状态快照（建议）：
+```bash
+aiws change state "${change_id}" --write
+```
+2) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接使用最小收尾闭环：
+```bash
+# 若当前就在 change/<change-id> 分支上，可省略 <change-id>
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "${change_id}" --push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "${change_id}" --push
+else
+  npx @aipper/aiws change finish "${change_id}" --push
+fi
+```
+说明：
+- 该命令会在 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；CLI 本身只有在显式传入 `--push` 时才会真正执行 push。
+
+3) 若你需要先处理 submodules，则不要依赖当前分支名推断目标分支，先显式解析 `base_branch`，再执行 submodule 步骤，最后回到主仓库执行 `aiws change finish --push`：
+```bash
+change_id="<change-id>"
+base_branch="$(python3 - <<'PY'
+import json, pathlib
+change_id = "<change-id>"
+meta = pathlib.Path("changes") / change_id / ".ws-change.json"
+data = json.loads(meta.read_text(encoding="utf-8"))
+print((data.get("base_branch") or "").strip())
+PY
+)"
+test -n "$base_branch"
+```
+4) 若 fast-forward 失败（提示需要 rebase）：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若存在 `.gitmodules`，先把每个 submodule 的 gitlink commit 合并回其目标分支（解决 detached HEAD），并按顺序 push：
+```bash
+# 不要用当前分支名代替目标分支；这里显式使用 .ws-change.json 的 base_branch
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
+
+# 子模块清单（没有则跳过）
+git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true
+
+# 对每个 submodule.<name>.path <sub_path>：
+# 说明：`git submodule update` 会把 submodule checkout 到固定 gitlink commit，导致 detached HEAD。
+# 为减少游离状态的协作摩擦，本步骤采用 pin 分支策略：
+# - `changes/<change-id>/submodules.targets` 是本次 finish/push 的真值；每个 submodule path 都必须在该文件中声明目标分支（可选 remote）
+# - `.gitmodules` 的 `submodule.<name>.branch` 仍建议保留，用于团队默认配置与校验，但不再作为 finish/push 的 fallback
+# - 生成/检查 `submodules.targets` 时可显式说明默认来源：
+#   - detached HEAD：默认建议取 `.gitmodules` 的 `submodule.<name>.branch`
+#   - 已附着在某个本地分支：默认建议取当前分支
+#   - 以上仅为预填建议；真正执行 finish/push 时仍只认 `submodules.targets`
+# - 不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来解 detached
+# - 不改动 submodule 现有分支指针（例如不强行移动 main/master）
+# - 创建/更新本地 pin 分支：`aiws/pin/<target_branch>` 指向 gitlink commit，并将其 upstream 设为 `origin/<target_branch>`
+if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+  if [[ ! -f "${targets}" ]]; then
+    echo "error: missing ${targets} (required when .gitmodules declares submodules)"
+    exit 2
+  fi
+
+  source tools/ws_resolve_sub_target.sh
+
+  while read -r key sub_path; do
+      name="${key#submodule.}"; name="${name%.path}"
+      [[ -z "${sub_path:-}" ]] && continue
+      echo "== submodule: ${sub_path} (${name}) =="
+
+      current_branch="$(git -C "${sub_path}" branch --show-current 2>/dev/null || true)"
+      declared_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+      if [[ -n "${current_branch}" ]]; then
+        echo "info: ${sub_path} default suggestion would be current branch: ${current_branch}"
+      elif [[ -n "${declared_branch}" ]]; then
+        echo "info: ${sub_path} default suggestion would be .gitmodules branch: ${declared_branch}"
+      else
+        echo "warn: ${sub_path} has no current branch and no .gitmodules branch; submodules.targets must be filled manually"
+      fi
+
+      sub_sha="$(git rev-parse "HEAD:${sub_path}")"
+
+      ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
+      target_branch="${_resolved_branch}"
+      remote="${_resolved_remote}"
+      pin_branch="aiws/pin/${target_branch}"
+
+      git -C "${sub_path}" fetch "${remote}" --prune
+      if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
+        echo "error: ${sub_path}: missing ${remote}/${target_branch}; refusing to push superproject (would break gitlink fetchability)"
+        exit 2
+      fi
+
+      # 仅当 gitlink commit 属于 <remote>/<target_branch> 的历史时才挂回分支
+      if ! git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "${remote}/${target_branch}"; then
+        echo "[warn] ${sub_path}: ${sub_sha} is not in ${remote}/${target_branch}; keep detached and stop (need manual reconcile)"
+        exit 1
+      fi
+
+      git -C "${sub_path}" checkout -B "${pin_branch}" "${sub_sha}"
+      git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "${pin_branch}" >/dev/null 2>&1 || true
+      git -C "${sub_path}" status -sb
+
+      # push：只允许 fast-forward（若远端分叉会被拒绝；此时必须人工处理）
+      git -C "${sub_path}" push "${remote}" "${sub_sha}:refs/heads/${target_branch}"
+    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+fi
+```
+规则：
+- 每个 submodule 必须先执行 pin 分支挂回 + fast-forward push，再 push 主仓库。
+- 若任一 submodule 的 gitlink commit 不在 `<remote>/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
+
+6) 仅当 submodules 全部成功后，再在 superproject 当前分支执行最小收尾闭环：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "${change_id}" --push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "${change_id}" --push
+else
+  npx @aipper/aiws change finish "${change_id}" --push
+fi
+```
+说明：
+- 该命令内部已经包含主仓库 push 成功后安全清理独立 change worktree 的逻辑。
+- 当 `--push` 完整成功时，还会自动把 `changes/<change-id>/` 归档到 `changes/archive/...`，生成 `handoff.md`，并补一个 `归档: <change-id>` commit。

package/templates/workspace/.claude/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/.claude/skills/ws-handoff/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ws-handoff
+description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
+- 若存在协同工件：在 handoff 中一并概述 `analysis/`、`patches/`、`review/`、`evidence/`
+- 指引在归档与依赖场景下如何使用 handoff
+
+说明：
+- `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
+```
+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/.claude/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/.claude/skills/ws-plan/SKILL.md

@@ -0,0 +1,138 @@
+---
+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`
+
+约束：
+- 不写入任何 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`（读取真值文件并输出约束摘要）。
+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`。
+
+补充：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`）