@aipper/aiws-spec 0.0.27 → 0.0.29

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 ws-push`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-push
 
-目标：
-- 在不自动提交的前提下，安全 push 当前仓库
-- 若仓库包含 submodules：按 `submodules -> superproject` 顺序 push，减少“别人拉取后子模块 detached/分叉”的协作摩擦
-- 若不包含 submodules：按普通 git 仓库的规则 push
+Thin skill wrapper. Delegates to `aiws ws-push`. See `aiws ws-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 ws-push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws ws-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 ws-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。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -1,6 +1,6 @@
 ---
 name: ws-req-contract-validate
-description: 合同校验（requirements contract validate）
+description: 使用时机：需要校验需求合同完整性时。触发词：合同校验、contract validate、需求核对。注意：合同未同步请先 ws-req-contract-sync。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -1,6 +1,6 @@
 ---
 name: ws-req-flow-sync
-description: Flow 同步（生成 api-flow 与场景执行合同）
+description: 使用时机：需要同步 API flow 和场景执行合同时。触发词：flow 同步、api flow、场景合同。注意：flow 定义变更请先 ws-req-change。
 ---
 
 用中文输出；命令与路径保持原样不翻译。

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

@@ -1,6 +1,6 @@
 ---
 name: ws-req-review
-description: 需求评审（对齐真值与验收）
+description: 使用时机：需要评审需求、验收条件、合同时。触发词：需求评审、验收评审、合同评审。注意：需求已确认直接进 ws-plan。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -1,11 +1,12 @@
 ---
 name: ws-review
-description: 评审（提交前审计与证据落盘）
+description: 使用时机：需要审计当前改动、查找风险时。触发词：审计、评审、review、风险检查、回归检查。注意：高风险变更应补 ws-spec-review + ws-quality-review。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+若当前语境已经明确是“准备交付/finish”，则本入口不应只停留在通用 review：应继续同时补齐 `$ws-spec-review` 与 `$ws-quality-review`，把 dual review gate 一次性收敛完。
 
 OpenCode + oMo 优先策略：
 - 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore` / `librarian`，优先借用这些 agent 做 review。
@@ -42,11 +43,21 @@ OpenCode + oMo 优先策略：
    - 是否有可复现验证命令与证据
    - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
    - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
-3) 将审计落盘到（目录不存在则创建）：
+3) Workflow State Suffix 审计（检查 4 种后缀使用是否一致）：
+   - `session` 后缀：只由 ws-dev-lite / ws-intake 写入，标记会话级进度（如 `[workflow-state:session:in_progress]`）
+   - `gate` 后缀：由 ws-dev / ws-plan-verify 写入，标记计划/实现门禁结果（如 `[workflow-state:gate:plan_passed]`）
+   - `plan` 后缀：由 ws-plan 写入，标记计划阶段状态（如 `[workflow-state:plan:in_progress]`）
+   - `gateway` 后缀：由 ws-finish / ws-deliver 写入，标记交付门禁结果（如 `[workflow-state:gateway:finish_gate_ok]`）
+   - 检查当前 change 中使用的后缀类型是否正确对应所在阶段；若出现混用（如 session 与 gate 在同一文件），在审计报告中标记异常并说明应该修正的方向。
+4) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-4) 回复中输出：
+5) 若当前任务已进入"准备提交/交付/finish"的语境，继续补齐 dual review gate：
+   - 运行/收敛 `$ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`（或回退 `.agentdocs/tmp/review/spec-review.md`）
+   - 运行/收敛 `$ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`（或回退 `.agentdocs/tmp/review/quality-review.md`）
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+6) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

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

@@ -1,6 +1,6 @@
 ---
 name: ws-rule
-description: 规则（解释项目规则与边界）
+description: 使用时机：需要了解项目规则、边界、约束时。触发词：规则、边界、约束、规范、约定。注意：只查询不改代码。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -1,6 +1,6 @@
 ---
 name: ws-spec-review
-description: 规范审查（requirements / plan / evidence / gate 完整性）
+description: 使用时机：需要审查流程完整性、requirements 归因时。触发词：规范审查、流程审计、spec review。注意：实现质量审查请用 ws-quality-review。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

package/templates/workspace/.opencode/skills/ws-submodule-setup/SKILL.md

@@ -1,65 +1,18 @@
 ---
 name: ws-submodule-setup
-description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch；减少 detached 与人为差异）
+description: Thin wrapper for `aiws ws-submodule-setup`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-submodule-setup
 
-目标：
-- 为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`，让 `ws-pull` / `ws-finish` 能确定性地“挂回分支/fast-forward push”，避免 origin 多分支时靠猜导致偏差。
-- 该变更是 **superproject 的团队真值**：需要提交 `.gitmodules`。
+Thin skill wrapper. Delegates to `aiws ws-submodule-setup`. See `aiws ws-submodule-setup --help` for details.
 
-安全约束（强制）：
-- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
-- 不在 submodule 中做破坏性操作（不 `reset --hard` / 不改动远端）
-
-步骤（建议）：
-1) 确认工作区干净（否则停止）：
-```bash
-git status --porcelain
-```
-
-2) 列出 submodules（没有则停止并说明无需配置）：
-```bash
-test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
-```
-
-3) 对每个 submodule，输出当前配置与建议分支（让用户确认每个 submodule 的 branch）：
-```bash
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  echo "== submodule: ${name} path=${sub_path} =="
-  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
-  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
-  git -C "${sub_path}" branch -r --list "origin/*" | sed -n '1,30p' || true
-  echo "[choose] set one of:"
-  echo "  - a concrete branch, e.g. main / master / release/x.y"
-  echo "  - '.' to follow superproject current branch name (only if your team uses matching branch names)"
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
-```
-
-4) 逐个写入分支配置（每次写完都回显，避免误配）：
 ```bash
-# Example:
-# git submodule set-branch --branch main path/to/submodule
-# git submodule set-branch --branch .    path/to/submodule
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws ws-submodule-setup
+elif command -v aiws >/dev/null 2>&1; then
+  aiws ws-submodule-setup
+else
+  npx @aipper/aiws ws-submodule-setup
+fi
 ```
-
-5) 输出变更并让用户确认是否提交：
-```bash
-git diff -- .gitmodules
-git status --porcelain
-```
-
-6) 若用户确认要提交：
-```bash
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branches"
-```
-
-输出要求：
-- `Submodules:` name/path + 选择的 branch（每个都列出）
-- `Diff:` `.gitmodules` 的 diff（或至少 `git diff -- .gitmodules` 的摘要）
-- `Next:` 提示后续用 `$ws-pull` 拉取可自动减少 detached；`aiws validate` 会检查该配置是否齐全
-

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

@@ -1,59 +1,18 @@
 ---
 name: ws-verify-before-complete
-description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+description: Thin wrapper for `aiws ws-verify-before-complete`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-verify-before-complete
 
-目标：
-- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
-- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+Thin skill wrapper. Delegates to `aiws ws-verify-before-complete`. See `aiws ws-verify-before-complete --help` for details.
 
-阶段定位：
-- finish 前 gate；负责 completion readiness 检查，不直接做 merge / push / handoff。
-
-必需输入：
-- `changes/<change-id>/review/spec-review.md`
-- `changes/<change-id>/review/quality-review.md`
-- `.agentdocs/tmp/aiws-validate/*.json`
-- 若存在：`changes/<change-id>/evidence/...`、`git status`
-
-必需输出：
-- `证据（Evidence）:` `changes/<change-id>/evidence/verify-before-complete.md` 或回退 `.agentdocs/tmp/review/verify-before-complete.md`
-- `结论（Result）:` pass / fail
-- `缺失项（Missing）:` 未满足的 gate
-- `下一步（Next）:` 进入 `$ws-finish` / `$ws-handoff`，或回退前置 gate
-
-阻断条件：
-- 缺少 spec review
-- 缺少 quality review
-- 缺少 validate stamp
-- review 中仍有未关闭 blocker
-- 无法写 verification 证据
-
-完成判定：
-- 已落盘 verify-before-complete 证据，并明确能否进入 `$ws-finish` / `$ws-handoff`。
-
-步骤（建议）：
-1) 识别当前 `change/<change-id>`。
-2) 检查以下最小 gate：
-   - `changes/<change-id>/review/spec-review.md`
-   - `changes/<change-id>/review/quality-review.md`
-   - `.agentdocs/tmp/aiws-validate/*.json`
-3) 若存在 `changes/<change-id>/evidence/`，检查是否已经收敛 review / validate / collaboration summary。
-4) 将结果落盘到：
-   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
-   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
-5) 输出：
-   - `证据（Evidence）:`
-   - `结论（Result）: pass|fail`
-   - `缺失项（Missing）:`
-   - `下一步（Next）:`
-
-重点：
-- 这个 gate 不替代 `$ws-finish`；它只判断“是否具备进入 finish / handoff 的前置条件”。
-- 若 fail，必须明确回退到哪个 gate：`$ws-spec-review`、`$ws-quality-review`、`aiws validate . --stamp` 或 `aiws change evidence <change-id>`。
-
-安全：
-- 不打印 secrets。
-- 不执行破坏性命令。
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws ws-verify-before-complete
+elif command -v aiws >/dev/null 2>&1; then
+  aiws ws-verify-before-complete
+else
+  npx @aipper/aiws ws-verify-before-complete
+fi
+```

package/templates/workspace/AGENTS.md

@@ -9,15 +9,16 @@
 - 不确定先跑 `/using-aiws`（Codex 对应 `$using-aiws`）；它会先读真值，再把任务路由到合适的 `ws-*` 入口。
 - 若你已经明确只是做预检，也可以直接跑 `/ws-preflight`（Codex 对应 `$ws-preflight`）；所有实现/修复都以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准。
 - 每次变更建议进入 `change/<change-id>`，并维护 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）。
-- 若仓库存在 `.gitmodules`：优先 `aiws change start <change-id> --worktree`；不要在当前 superproject worktree 里直接切分支。
+- 若仓库存在 `.gitmodules`：使用 `aiws change start <change-id> --switch`；不要在当前 superproject 里直接手工切分支。
 - 提交前执行 `aiws validate .`；需要本机门禁时运行 `aiws hooks install .`（或 `git config core.hooksPath .githooks`）。
 - 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等。
 
 标准链路（建议默认）：
 - `using-aiws`：默认 bootstrap/router；先读真值，先判 workflow，再进入具体阶段；意图不明确时先澄清。
 - `ws-preflight`：读取真值文件，输出约束摘要；若真值缺失，先停止，不直接开工。
+- `ws-intake`：计划前置澄清；适用于新需求或中大型变更，按“一题一线程”逐条冻结问题，产出 `plan/*.intake.md` 轻量草案。
 - `ws-plan`：建立 `change/<change-id>` 绑定，落盘 `plan/...`，明确 Verify / Risks / Evidence。
-- `ws-plan-verify`：在编码前做计划质检；不过门禁就先修 plan，不跳步进实现。
+- `ws-plan-verify`：在编码前做计划质检 + 多视角方案审查；不过门禁就先修 plan，不跳步进实现。
 - `ws-dev`：只做可归因、可验证的小步实现；输出 Changed / Verify / Evidence。
 - `ws-dev-lite`：`ws-dev` 的轻量入口；适用于 simple/local 单点修复，默认不建 `plan/...`、不跑 `ws-plan-verify`，治理归属仍收敛到 `ws-dev`。
 - `ws-delegate`：仅在任务已绑定且 scope 可控时，使用原生多 agent / sub-agent；否则明确降级为单 agent + 协同工件模式。
@@ -30,6 +31,7 @@
 - `ws-handoff`：查看/补充归档后的 handoff，给下一次会话或下一位协作者接力。
 
 阶段产物（最少）：
+- intake：`plan/*.intake.md`
 - planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
 - implementation：代码 / 配置改动 + Verify 命令记录
 - collaboration：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`
@@ -40,14 +42,18 @@
 OpenCode（如果你主要用 OpenCode，优先）：
 - native skills 在 `.opencode/skills/`；native commands 在 `.opencode/commands/`
 - 若项目启用了 `.opencode/oh-my-opencode.json`：`ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 会优先借用 oMo 的 `planner-sisyphus` / `explore` / `librarian` / `oracle`
-- 若你想按项目固定这组 agent，可参考 `.opencode/oh-my-opencode.json.example`；它只覆盖 `agents`，不接管 hooks/MCP/LSP
+- 若你想按项目固定这组 agent，可参考 `.opencode/oh-my-opencode.json.example`；它提供 autonomy 示例配置，但仍不接管 hooks/MCP/LSP/runtime
+- 若你要做实验性的“尽量无人值守直到完成”：先看 `/ws-auto`、`/ws-autonomy`、`.claude/settings.json.example` 与 `.opencode/helpers/tmux-swarm-*.sh`
 - 常用手动入口继续保留在 `.opencode/commands/`（migration window 内 `.opencode/command/` 也会保留）；直接使用 `/ws-*`
 - 若你不确定当前任务该先 plan、dev、review 还是 finish：先用 `/using-aiws`
+- 需求还没冻结、想逐条把问题聊清楚：先用 `/ws-intake`
 - `/ws-preflight`：读取真值文件并输出约束摘要
-- `/ws-plan` / `/ws-plan-verify`：先生成计划，再做执行前质检
+- `/ws-plan` / `/ws-plan-verify`：先生成计划，再做执行前质检与多视角方案审查
 - `/ws-dev`：常规实现/改配置/改测试
 - `/ws-dev-lite`：小问题直修；若复杂度升高，立刻回到 `/ws-dev` 或 `/ws-plan`
 - `/ws-delegate`：按 AIWS 委托合同拆分子任务，并优先借用 oMo agent
+- `/ws-auto`：OpenCode/oMo 自动 bootstrap 入口；会先检查托管内容/是否需要 update，再按条件确保 watchdog 已启动
+- `/ws-autonomy`：OpenCode/oMo 自主协作实验入口；声明 completion/retry/rescue 合同，不接管 runtime controller
 - `/ws-bugfix`：缺陷修复 + 证据落盘 + CSV 汇总
 - `/ws-review` / `/ws-commit`：提交前审计、门禁与 commit
 - `/ws-spec-review` / `/ws-quality-review`：高风险改动建议显式拆成流程审查 + 质量审查
@@ -60,13 +66,14 @@ Claude Code（如果你主要用 Claude Code）：
 - native skills 在 `.claude/skills/`；command-style 兼容入口保留在 `.claude/commands/`
 - 常用链路可按 `ws-*` / `p-aiws-*` 理解；native skills 与 compatibility commands 指向同一套 AIWS workflow
 - 若你不确定当前任务该走哪个阶段：先用 `/using-aiws`
+- 需求还没冻结、想逐条把问题聊清楚：先用 `/ws-intake`
 - 高风险改动或准备 finish 时，建议额外跑 `/ws-spec-review`、`/ws-quality-review`、`/ws-verify-before-complete`
 
 Codex（对应入口，可选）：
 - 若你不想先记住阶段，先用 `$using-aiws` 让 router 判定下一步
 - 对应入口在 `.agents/skills/`；显式调用时使用 `$ws-*`
 - `$using-aiws`
-- `$ws-preflight` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-dev-lite` / `$ws-delegate` / `$ws-frontend-design`
+- `$ws-preflight` / `$ws-intake` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-dev-lite` / `$ws-delegate` / `$ws-frontend-design`
 - `$ws-review` / `$ws-spec-review` / `$ws-quality-review` / `$ws-commit`
 - `$ws-verify-before-complete` / `$ws-finish` / `$ws-deliver`
 - `$ws-pull` / `$ws-push` / `$ws-submodule-setup`

package/templates/workspace/AI_PROJECT.md

@@ -38,7 +38,7 @@
 推荐（防规则/范围漂移）：
 - 创建工件：补齐 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
 - 声明 active change（团队共享）：切到分支 `change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若仓库存在 `.gitmodules`：优先使用 `aiws change start <change-id> --worktree`（或至少 `--no-switch`）；不要在当前 superproject worktree 里直接手工切分支。
+- 若仓库存在 `.gitmodules`：使用 `aiws change start <change-id> --switch`；不要在当前 superproject 里直接手工切分支。
 - 若 submodule 因 gitlink checkout 处于 detached HEAD：只允许挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来“解 detached”。
 - 严格校验：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - 启用 hooks（本地生效）：`git config core.hooksPath .githooks`（提交/推送时自动跑 `aiws validate .`）

package/templates/workspace/changes/README.md

@@ -32,14 +32,11 @@ changes/
 - `aiws change new <change-id>` 会预创建以上目录，减少临时约定漂移。
 
 常用命令（推荐使用 `aiws`；不依赖 dotfiles）：
-- `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录；若检测到 `.gitmodules` 则默认优先使用 worktree，失败则回退为不切分支，避免 submodule 状态混乱）
+- `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录）
 - `aiws change start <change-id> --no-switch`（superproject + submodule 场景：不切分支，仅准备 `change/<change-id>` 分支与工件目录）
-- `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅切 superproject，不递归切换 submodule；仅在存在 `.gitmodules` 时有意义）
-- `aiws change start <change-id> --worktree`（推荐用于 superproject + submodule：创建独立 worktree；当前目录分支保持不变）
-  - 可选：`--worktree-dir <path>` 覆盖 worktree 目录
-  - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`
+- `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅切 superproject，不递归切换 submodule）
 - `aiws change finish <change-id>`（安全合并：fast-forward 合并回目标分支；在 `change/<change-id>` 分支上执行时会尝试使用 `.ws-change.json` 的 `base_branch` 作为目标分支）
-- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则在 push 成功后自动执行 worktree cleanup，并把 `changes/<id>/` 自动归档到 `changes/archive/...`，同时生成 `handoff.md` 与 archive commit）
+- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；push 成功后把 `changes/<id>/` 自动归档到 `changes/archive/...`，同时生成 `handoff.md` 与 archive commit）
 - 已 archive 的 `change/<change-id>` 才算真正终态；若只是“已 finish 但仍有 active `changes/<id>/` 未归档”，默认应重跑 `aiws change finish <change-id> --push` 续完收尾，而不是继续开发或复用旧 branch 做新需求。
 - `aiws change new <change-id>`
 - `aiws change list`
@@ -55,10 +52,10 @@ Active change（推荐，团队共享）：
 - 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync`
 
 计划质量门（推荐，执行前）：
-- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支 / worktree，再在该上下文内写 `plan/...`）
+- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支，再在该上下文内写 `plan/...`）
 - 再执行计划质检：`$ws-plan-verify`
 - 最后进入实现：`$ws-dev`
-- 若 `$ws-plan` 创建了独立 worktree，后续 `$ws-plan-verify` / `$ws-dev` / `$ws-finish` 都应优先在该 worktree 内继续
+- 若 `$ws-plan` 创建了独立 `change/<change-id>` 分支，后续 `$ws-plan-verify` / `$ws-dev` / `$ws-finish` 都应优先在该分支内继续
 - 目标：确保计划具备主索引绑定、步骤不过长、验证命令可复现且有预期结果
 
 模板覆盖（可选）：
@@ -88,10 +85,10 @@ Hooks/CI（推荐，硬约束）：
 - 紧急跳过（不推荐）：`WS_CHANGE_HOOK_BYPASS=1 ...`（CI 不应允许跳过）。
 
 合并建议（减少人为 merge 引入新问题）：
-- 优先使用 worktree + fast-forward 合并：
-  - 完成后在主工作区（例如 `main`）执行：`aiws change finish <change-id>`（等价于 `git merge --ff-only change/<change-id>`）
-  - 若还要顺手 push 并清理独立 change worktree：`aiws change finish <change-id> --push`
-  - 若失败：先在 worktree 里 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`
+- 优先使用 fast-forward 合并：
+  - 完成后在目标分支（例如 `main`）执行：`aiws change finish <change-id>`（等价于 `git merge --ff-only change/<change-id>`）
+  - 若还要顺手 push：`aiws change finish <change-id> --push`
+  - 若失败：先在 change 分支 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`
 
 协同交付建议：
 - 委托分析先落到 `changes/<id>/analysis/`，由主 agent 在 `ws-review` 或 `review/*.md` 中收敛结论。