@aipper/aiws-spec 0.0.29 → 0.0.31

package/templates/workspace/.agents/skills/p-aiws-change-new/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: p-aiws-change-new
-description: 私有：创建 changes/<change-id> 工件
+description: 私有：创建 .aiws/changes/<change-id> 工件
 ---
 
 目标：
-- 创建 `changes/<change-id>/` 工件目录与基础文件（proposal/tasks/可选 design）
+- 创建 `.aiws/changes/<change-id>/` 工件目录与基础文件（proposal/tasks/可选 design）
 
 要求：
 - `change-id` 必须是 kebab-case：`^[a-z0-9]+(-[a-z0-9]+)*$`

package/templates/workspace/.agents/skills/p-aiws-change-start/SKILL.md

@@ -4,7 +4,7 @@ description: 私有：切分支并初始化变更工件（可选安装 hooks）
 ---
 
 目标：
-- 切到分支 `change/<change-id>` 并初始化 `changes/<change-id>/` 工件
+- 切到分支 `change/<change-id>` 并初始化 `.aiws/changes/<change-id>/` 工件
   - 若检测到 `.gitmodules`（git submodules），默认优先使用 `--worktree`（失败则回退为 `--no-switch`），避免切走 superproject 分支导致 submodule 状态混乱
 
 要求：

package/templates/workspace/.agents/skills/p-aiws-change-sync/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: p-aiws-change-sync
-description: 私有：同步真值基线到 changes/<change-id>（写入 .ws-change.json）
+description: 私有：同步真值基线到 .aiws/changes/<change-id>（写入 .ws-change.json）
 ---
 
 目标：
-- 将当前真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）的 hash 快照同步到 `changes/<change-id>/.ws-change.json`
+- 将当前真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）的 hash 快照同步到 `.aiws/changes/<change-id>/.ws-change.json`
 
 执行（在仓库根目录）：
 ```bash

package/templates/workspace/.agents/skills/p-aiws-change-validate/SKILL.md

@@ -4,7 +4,7 @@ description: 私有：校验 changes 工件（可 strict）
 ---
 
 目标：
-- 校验 `changes/<change-id>/` 工件完整性、归因与 WS:TODO（用于 hooks/CI）
+- 校验 `.aiws/changes/<change-id>/` 工件完整性、归因与 WS:TODO（用于 hooks/CI）
 
 执行（在仓库根目录）：
 ```bash

package/templates/workspace/.agents/skills/p-aiws-validate/SKILL.md

@@ -19,4 +19,4 @@ fi
 ```
 
 证据（可选）：
-- stamp：`.agentdocs/tmp/aiws-validate/*.json`（由 `.gitignore` 忽略）
+- stamp：`.aiws/tmp/aiws-validate/*.json`（由 `.gitignore` 忽略）

package/templates/workspace/.agents/skills/p-tasks-plan/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: p-tasks-plan
-description: 原子：tasks 同步（从 changes/<id>/tasks.md 生成 update_plan payload）
+description: 原子：tasks 同步（从 .aiws/changes/<id>/tasks.md 生成 update_plan payload）
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 用 `changes/<change-id>/tasks.md` 的 checkbox 任务作为“步骤真值”
+- 用 `.aiws/changes/<change-id>/tasks.md` 的 checkbox 任务作为“步骤真值”
 - 生成可直接用于 `update_plan` 的 JSON payload（`pending/in_progress/completed`）
 - 输出当前进度摘要（done/total + 当前 in_progress）
 
 约束：
 - 不写入任何 secrets（token、账号、内网端点等不得进入 git）
-- 只读 `changes/<id>/tasks.md`（不自动改写 tasks 文件）
+- 只读 `.aiws/changes/<id>/tasks.md`（不自动改写 tasks 文件）
 - 未运行不声称已运行
 
 执行步骤（建议）：
@@ -20,18 +20,18 @@ description: 原子：tasks 同步（从 changes/<id>/tasks.md 生成 update_pla
 2) 推断 `change-id`：
    - 优先从当前分支名读取：`git rev-parse --abbrev-ref HEAD`（期望形如 `change/<change-id>`）
    - 若无法推断：让用户明确本次要同步的 `<change-id>`
-3) 检查 tasks 文件存在：`test -f changes/<change-id>/tasks.md`
+3) 检查 tasks 文件存在：`test -f .aiws/changes/<change-id>/tasks.md`
 4) 输出进度摘要：
 ```bash
-python3 tools/ws_tasks_plan.py status --file changes/<change-id>/tasks.md
+python3 tools/ws_tasks_plan.py status --file .aiws/changes/<change-id>/tasks.md
 ```
 5) 生成 `update_plan` payload（JSON 输出到 stdout）：
 ```bash
-python3 tools/ws_tasks_plan.py plan --file changes/<change-id>/tasks.md --explanation "sync tasks.md -> update_plan"
+python3 tools/ws_tasks_plan.py plan --file .aiws/changes/<change-id>/tasks.md --explanation "sync tasks.md -> update_plan"
 ```
 6) 调用 `update_plan`，将上一步 JSON 原样作为入参（确保任意时刻最多 1 条 `in_progress`）。
 
 输出要求：
 - `Change_ID:` <change-id>
-- `Tasks:` `changes/<change-id>/tasks.md`
+- `Tasks:` `.aiws/changes/<change-id>/tasks.md`
 - `Next:` 推荐下一步（通常为继续完善 tasks 或进入 `$ws-dev`）

package/templates/workspace/.agents/skills/using-aiws/SKILL.md

@@ -19,7 +19,7 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
 - `AI_PROJECT.md`
 - `REQUIREMENTS.md`
 - `AI_WORKSPACE.md`
-- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`.aiws/changes/<change-id>/...`
 
 必需输出：
 - `Root:` 当前项目根
@@ -55,8 +55,8 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
     - finish / merge / push / cleanup：`$ws-finish`
     - handoff / archive summary：`$ws-handoff`
     - 新需求或中大型变更，且存在多条待确认问题 / 用户要求逐条多轮沟通：`$ws-intake`
-    - 需要先出设计方案（design 未过审前不进入实现）：`$ws-design`
-    - 需要更新规范/验收标准（必须先过 review）：`$ws-spec-update`
+    - 需要先出设计方案（design 作为 plan 阶段一部分）：`$ws-plan`
+    - 需要更新规范/验收标准（必须先过 req-review）：`$ws-req-change`
     - 中大型实现、需要方案、需要 change/worktree，且需求已经冻结：`$ws-plan`
    - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
 4) 若任务意图或归因不明确：
@@ -81,10 +81,14 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
    - 否则：
      - `Next:` 进入对应主 skill
    - 然后在同一轮中继续遵循对应 skill 的契约
-7) 路由约束：
-   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
-   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
-   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+ 7) 路由约束：
+    - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+    - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+    - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+    - **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——具体检查：`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+    - **Subagent 不可用时**：降级为当前 agent 直接执行，但必须在 evidence 中记录降级原因
+   - **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+   - Subagent 不可用时的降级路径：`ready-for-dev` → 当前 agent 直接执行 ws-dev；`in-progress` → 当前 agent 自审（evaluate-optimize 1 轮）；`review` → 当前 agent 本地 review（不阻断）。降级时必须在 evidence 中记录降级原因
 8) 若执行过程中发现复杂度升高：
    - 从 `$ws-dev` 回退到 `$ws-plan`
    - 从 `$ws-plan` 回退到 `$ws-intake`（当发现需求并未冻结）

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

@@ -5,7 +5,7 @@ description: 分析（定位问题与收集上下文）
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.aiws/tmp/analyze/`。
 
 输入：
 - 主题/需求：用户在本次消息中提供的主题（若不明确，先问一句“本次分析主题是什么？”）
@@ -18,7 +18,7 @@ description: 分析（定位问题与收集上下文）
    - 推荐方案（1 个）+ 备选（可选）
    - 风险与回滚（3–8 条）
    - 最小验证命令（可复现）
-3) 将分析落盘到：`.agentdocs/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
+3) 将分析落盘到：`.aiws/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
 4) 回复中必须包含：`Evidence:` 证据文件路径。
 
 安全：

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

@@ -1,13 +1,13 @@
 ---
 name: ws-bugfix
-description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片证据，汇总到 issues/fix_bus_issues.csv，并绑定到 changes/<change-id>/）
+description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片证据，汇总到 issues/fix_bus_issues.csv，并绑定到 .aiws/changes/<change-id>/）
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
 - 用禅道 MCP 拉取 bug 详情与附件（尤其图片）
-- 把证据落盘到 `changes/<change-id>/bug/`（避免只停留在对话）
+- 把证据落盘到 `.aiws/changes/<change-id>/bug/`（避免只停留在对话）
 - 把修复任务汇总/更新到 `issues/fix_bus_issues.csv`
 - 与 `ws-dev` / `aiws change` 流程绑定，确保可追溯、可验证
 
@@ -21,7 +21,7 @@ description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片
 2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
 3) 建立 change 上下文（推荐先于任何落盘）：
    - 若当前还不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start`
-   - 工作区必须先干净；否则不要先写 `changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
+   - 工作区必须先干净；否则不要先写 `.aiws/changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
    - 仓库已有提交：优先 `--worktree`
    - superproject + submodule：优先 `--worktree --submodules`
    - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `--no-switch`
@@ -46,7 +46,7 @@ fi
      - 优先复用 `$ws-dev` 的 `submodules.targets` 生成/确认流程
      - detached HEAD 时默认建议取 `.gitmodules` 声明的分支
      - 已附着在某个本地分支时默认建议取当前分支
-     - 以上都只是建议值，最终必须显式写入 `changes/<change-id>/submodules.targets`
+     - 以上都只是建议值，最终必须显式写入 `.aiws/changes/<change-id>/submodules.targets`
 
 建议流程（按顺序）：
 
@@ -58,14 +58,14 @@ fi
 - 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
 
 ## 2) 证据落盘（强制）
-在当前 active change 上下文的 `changes/<change-id>/bug/` 下落盘：
+在当前 active change 上下文的 `.aiws/changes/<change-id>/bug/` 下落盘：
 - `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
 - `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
 - `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
 
 建议目录：
 ```text
-changes/<change-id>/bug/
+.aiws/changes/<change-id>/bug/
   zentao-bug-<bug-id>.json
   zentao-bug-<bug-id>.md
   images/<bug-id>/
@@ -83,7 +83,7 @@ Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Path
 
 字段约束：
 - `Change_ID`：必须等于当前 `change-id`
-- `Evidence_Path`：指向 `changes/<change-id>/bug/zentao-bug-<bug-id>.md`
+- `Evidence_Path`：指向 `.aiws/changes/<change-id>/bug/zentao-bug-<bug-id>.md`
 - `Image_Paths`：多个路径用 `;` 分隔
 - `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
 
@@ -107,5 +107,5 @@ aiws validate . --stamp
 - `Change_ID:` `<change-id>`
 - `Change context:` `<当前分支或 worktree 路径>`
 - `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
-- `Evidence:` `changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
+- `Evidence:` `.aiws/changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
 - `Verify:` 实际运行命令与结果（未运行不声称已运行）

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

@@ -1,18 +1,18 @@
 ---
 name: ws-commit
-description: `aiws ws-commit` 的薄包装入口
+description: `aiws commit` 的薄包装入口
 ---
 
 # ws-commit
 
-`aiws ws-commit` 的薄包装入口。
+`aiws commit` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-commit
+  ./node_modules/.bin/aiws commit
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-commit
+  aiws commit
 else
-  npx @aipper/aiws ws-commit
+  npx @aipper/aiws commit
 fi
 ```

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

@@ -55,10 +55,10 @@ description: 原生多 agent 委托入口（Codex 优先；先定义角色/边
 5) 若当前环境不支持，或无法稳定约束 scope：
    - 明确输出 `Execution Mode: fallback single-agent`
    - 仍按 AIWS 协同工件约定执行：
-     - `changes/<id>/analysis/`
-     - `changes/<id>/patches/`
-     - `changes/<id>/review/`
-     - `changes/<id>/evidence/`
+     - `.aiws/changes/<id>/analysis/`
+     - `.aiws/changes/<id>/patches/`
+     - `.aiws/changes/<id>/review/`
+     - `.aiws/changes/<id>/evidence/`
 6) 不论是否启用原生多 agent，都不要跳过：
    - 需求归因
    - 验证命令

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

@@ -1,18 +1,18 @@
 ---
 name: ws-deliver
-description: `aiws ws-deliver` 的薄包装入口
+description: `aiws deliver` 的薄包装入口
 ---
 
 # ws-deliver
 
-`aiws ws-deliver` 的薄包装入口。
+`aiws deliver` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-deliver
+  ./node_modules/.bin/aiws deliver
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-deliver
+  aiws deliver
 else
-  npx @aipper/aiws ws-deliver
+  npx @aipper/aiws deliver
 fi
 ```

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

@@ -20,7 +20,7 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 
 - `变更文件（Changed）:` 实际改动清单
 - `验证（Verify）:` 实际运行的命令与结果说明
-- `证据（Evidence）:` `plan/...`、`changes/<change-id>/...`、`.agentdocs/tmp/...` 等证据路径
+- `证据（Evidence）:` `plan/...`、`.aiws/changes/<change-id>/...`、`.aiws/tmp/...` 等证据路径
 - `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
 
 ## 阻断条件
@@ -43,12 +43,23 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 - 已有计划：先 `$ws-plan-verify`，通过后进入实现。
 - `$ws-plan` 已创建 worktree：直接在该 worktree 中继续。
 
+### 1.5 Design Gate（入口检查）
+
+在进入实现前，先验证绑定工件是否完整：
+
+- 若计划或实际改动超过 2 个文件：**必须**检查 `.aiws/changes/<change-id>/` 下是否存在 `proposal.md` 和 `tasks.md`
+- 若缺失：**阻断**并输出信息 `Design Gate: proposal.md and tasks.md required for multi-file implementations. Run $ws-plan first.`
+- 若为单文件/小改动（≤2 文件）：此检查为 advisory 级别，缺失仅在输出中提示但不阻断
+- Design Gate 检查结果需记录在输出中，作为实现入口证据
+
+Design Gate 通过后，继续进入变更归因与实现。
+
 ### 2. 建立变更归因
 
 - 若 `git status --porcelain` 仅有计划/工件文件，属于预期行为，继续即可。
 - 若需创建新 change：`aiws change start <change-id> --hooks --no-switch`
 - 若需切换分支：先确认无额外未提交改动，再 `git switch change/<change-id>`
-- 若存在 submodule（`.gitmodules`）：进入编码前必须准备好 `changes/<change-id>/submodules.targets`。`aiws change start` 的 `--submodules` 标志会自动处理。参考 `changes/README.md` 和 `changes/<change-id>/submodules.targets` 格式。
+- 若存在 submodule（`.gitmodules`）：进入编码前必须准备好 `.aiws/changes/<change-id>/submodules.targets`。`aiws change start` 的 `--submodules` 标志会自动处理。参考 `changes/README.md` 和 `.aiws/changes/<change-id>/submodules.targets` 格式。
 
 ### 3. 实现策略：默认 dispatch aiws-worker（Subagent-First）
 
@@ -60,9 +71,28 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 - 根据 review 结果决定 fix 或收敛 evidence
 - **Inline escape hatch**：如果用户明确说"你直接改"或"do it inline"，主 session 可直接写代码，但必须落盘 evidence 记录理由
 
+### 3.1 自我修正循环（evaluate-optimize）
+
+收到 sub-agent 或自行产出实现后，执行自我修正循环：
+
+1. **Evaluate** — 检查实现质量：
+   - lint / typecheck 是否通过
+   - 是否遵循现有代码模式（文件结构、命名约定、错误处理风格）
+   - 是否有明显 bug 或边界缺失
+2. **Optimize** — 修复发现的问题（最多 2 轮）
+   - 每轮修复后重新 evaluate
+   - 若 2 轮后仍有问题 → escalate 到 `$ws-review`
+3. **TDD 优先** — 对于中大型改动，优先按 RED→GREEN→REFACTOR 顺序：
+   - RED：先写一个会失败的测试
+   - GREEN：实现最小代码让测试通过
+   - REFACTOR：在测试保护下重构
+
+注意：TDD 在简单修复时不强制，但对新增功能/中等以上复杂度变更建议遵循。
+
 ### 4. 其他规则
 
 - 需求调整：先 `$ws-req-review` → 确认后 `$ws-req-change`
+- **TDD 约束**：新增功能必须补测试（RED→GREEN→REFACTOR）；bug fix 至少补一条回归测试
 - 最小改动：每处改动必须归因到 `REQUIREMENTS.md` 或 `issues/problem-issues.csv`
 - 验证：运行 `AI_WORKSPACE.md` 声明的命令；未运行不声称已运行
 - 多步任务：使用 `update_plan` 工具跟踪状态

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

@@ -44,8 +44,8 @@ description: 轻量开发（simple/local 单点修复；最小改动 + 最小验
    - 若只需局部回归，允许运行更窄的验证，但要说明为什么足够
 5) 留下至少一个可追溯证据：
    - 实际改动文件
-   - 或 `.agentdocs/tmp/...`
-   - 或 `changes/<change-id>/...`
+   - 或 `.aiws/tmp/...`
+   - 或 `.aiws/changes/<change-id>/...`
 6) 输出：
    - `变更文件（Changed）:`
    - `验证（Verify）:`

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

@@ -1,18 +1,22 @@
 ---
 name: ws-finish
-description: `aiws ws-finish` 的薄包装入口
+description: `aiws finish` 的收尾入口（finish_resume_required）
 ---
 
 # ws-finish
 
-`aiws ws-finish` 的薄包装入口。
+`aiws finish` 的收尾入口。
+
+关键契约：
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`，继续执行 `aiws change finish <change-id> --push`
+- 普通 finish 的 `validate/evidence/state` 仍应在 `change/<change-id>` worktree 完成，不要在目标 worktree 里跑 `aiws validate . --stamp`
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-finish
+  ./node_modules/.bin/aiws finish
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-finish
+  aiws finish
 else
-  npx @aipper/aiws ws-finish
+  npx @aipper/aiws finish
 fi
 ```

package/templates/workspace/.agents/skills/ws-frontend-design/SKILL.md

@@ -123,4 +123,4 @@ app-ui 规则：
 - `Visual thesis:` 一句话
 - `Changed:` 改动文件清单
 - `Verify:` 实际运行命令 + 预期结果
-- `Evidence:` 相关 `plan/...`、`changes/<change-id>/...` 或截图/审计路径
+- `Evidence:` 相关 `plan/...`、`.aiws/changes/<change-id>/...` 或截图/审计路径

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

@@ -1,18 +1,18 @@
 ---
 name: ws-handoff
-description: `aiws ws-handoff` 的薄包装入口
+description: `aiws handoff` 的薄包装入口
 ---
 
 # ws-handoff
 
-`aiws ws-handoff` 的薄包装入口。
+`aiws handoff` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-handoff
+  ./node_modules/.bin/aiws handoff
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-handoff
+  aiws handoff
 else
-  npx @aipper/aiws ws-handoff
+  npx @aipper/aiws handoff
 fi
 ```

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

@@ -0,0 +1,18 @@
+---
+name: ws-migrate
+description: `aiws migrate` 的薄包装入口
+---
+
+# ws-migrate
+
+`aiws migrate` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws migrate
+elif command -v aiws >/dev/null 2>&1; then
+  aiws migrate
+else
+  npx @aipper/aiws migrate
+fi
+```

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

@@ -16,7 +16,7 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 - 不写入任何 secrets（token、账号、内网端点等不得进入 git）
 - 本 skill 只负责“想清楚怎么做 + 落盘计划”，不要直接大规模改动代码
 - 未运行不声称已运行；验证命令要写清“预期结果”
-- 若存在 `changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
+- 若存在 `.aiws/changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
 
 阶段定位：
 - planning 阶段；负责把用户目标收敛为 change 绑定、计划文件和验证入口。
@@ -25,7 +25,7 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 - 当前任务描述
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
 - 若已存在：最新 `plan/*.intake.md`
-- 若已存在：`changes/<change-id>/proposal.md`
+- 若已存在：`.aiws/changes/<change-id>/proposal.md`
 - 若已有计划：当前 `plan/...` 文件
 
 必需输出：
@@ -52,7 +52,7 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 3) 若用户任务描述不清，且也没有可消费的 intake 草案：先问 1-3 个关键澄清问题（不要猜）；若问题较多则回退到 `$ws-intake`
 4) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
 5) 识别或建立主索引 / change 上下文：
-   - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
+   - 若存在 `.aiws/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
    - 推荐顺序：
@@ -101,7 +101,7 @@ fi
    - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
    - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
-   - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
+   - `Evidence`：计划文件路径；若创建了变更工件则附 `.aiws/changes/<change-id>/...`
 8) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
 9) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
 10) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
@@ -111,7 +111,7 @@ fi
 - 背景：`.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`
+  - 文件：`.aiws/changes/<change-id>/submodules.targets`
   - 格式：每行一个 submodule（忽略空行与 `#` 注释），字段用空白分隔（推荐 `TAB`）：
     - 第 1 列：submodule path（例如 `vendor/foo`）
     - 第 2 列：target branch（例如 `release/channel-a`）

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

@@ -1,18 +1,18 @@
 ---
 name: ws-plan-verify
-description: `aiws ws-plan-verify` 的薄包装入口
+description: `aiws plan-verify` 的薄包装入口
 ---
 
 # ws-plan-verify
 
-`aiws ws-plan-verify` 的薄包装入口。
+`aiws plan-verify` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-plan-verify
+  ./node_modules/.bin/aiws plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-plan-verify
+  aiws plan-verify
 else
-  npx @aipper/aiws ws-plan-verify
+  npx @aipper/aiws plan-verify
 fi
 ```

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

@@ -0,0 +1,18 @@
+---
+name: ws-pull
+description: `aiws pull` 的薄包装入口
+---
+
+# ws-pull
+
+`aiws pull` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws pull
+elif command -v aiws >/dev/null 2>&1; then
+  aiws pull
+else
+  npx @aipper/aiws pull
+fi
+```

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

@@ -0,0 +1,18 @@
+---
+name: ws-push
+description: `aiws push` 的薄包装入口
+---
+
+# ws-push
+
+`aiws push` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws push
+else
+  npx @aipper/aiws push
+fi
+```

package/templates/workspace/.agents/skills/ws-quality-review/SKILL.md

@@ -7,7 +7,7 @@ description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
 
 目标：
 - 审查当前改动的行为正确性、边界条件、测试覆盖和实现质量
-- 把“代码/行为层 findings”优先落盘到 `changes/<change-id>/review/quality-review.md`
+- 把“代码/行为层 findings”优先落盘到 `.aiws/changes/<change-id>/review/quality-review.md`
 
 阶段定位：
 - review 子 gate；负责实现质量、行为回归与验证覆盖审查。
@@ -16,10 +16,10 @@ description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
 - 当前 `git diff`
 - 已执行的验证结果
 - 相关代码 / 配置 / 测试文件
-- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 review 文件
+- 若存在：`.aiws/changes/<change-id>/analysis/`、`patches/`、已有 review 文件
 
 必需输出：
-- `证据（Evidence）:` `changes/<change-id>/review/quality-review.md` 或回退 `.agentdocs/tmp/review/quality-review.md`
+- `证据（Evidence）:` `.aiws/changes/<change-id>/review/quality-review.md` 或回退 `.aiws/tmp/review/quality-review.md`
 - `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
 - `下一步（Next）:` 最小修复项与回归命令
 
@@ -39,8 +39,8 @@ description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
    - 测试是否足以支撑改动
    - 是否存在明显复杂度、耦合、可维护性或性能问题
 3) 将结论落盘到：
-   - 默认：`changes/<change-id>/review/quality-review.md`
-   - 回退：`.agentdocs/tmp/review/quality-review.md`
+   - 默认：`.aiws/changes/<change-id>/review/quality-review.md`
+   - 回退：`.aiws/tmp/review/quality-review.md`
 4) 输出：
    - `证据（Evidence）:`
    - `主要发现（Findings）:`

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

@@ -5,7 +5,7 @@ description: 评审（提交前审计与证据落盘）
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `.aiws/changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.aiws/tmp/review/`）。
 若当前语境已经明确是“准备交付/finish”，则本入口不应只停留在通用 review：应继续同时补齐 `$ws-spec-review` 与 `$ws-quality-review`，把 dual review gate 一次性收敛完。
 
 阶段定位：
@@ -16,10 +16,10 @@ description: 评审（提交前审计与证据落盘）
 - 已执行的验证结果
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
 - 当前 `change/<change-id>` 上下文（若能识别）
-- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
+- 若存在：`.aiws/changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
 
 必需输出：
-- 审计文件：`changes/<change-id>/review/codex-review.md` 或回退 `.agentdocs/tmp/review/codex-review.md`
+- 审计文件：`.aiws/changes/<change-id>/review/codex-review.md` 或回退 `.aiws/tmp/review/codex-review.md`
 - `主要风险（Top risks）:` 3-8 条
 - `下一步（Next）:` 最小修复清单 + 最小验证命令
 
@@ -35,15 +35,15 @@ description: 评审（提交前审计与证据落盘）
 2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据
-   - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+   - 是否维护了 `.aiws/changes/<change-id>/` 或相关 `issues/*.csv`
    - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
 3) 将审计落盘到（目录不存在则创建）：
-   - 默认：`changes/<change-id>/review/codex-review.md`
-   - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
+   - 默认：`.aiws/changes/<change-id>/review/codex-review.md`
+   - 回退：`.aiws/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
 4) 若当前任务已进入“准备提交/交付/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`）
+   - 运行/收敛 `$ws-spec-review`，落盘 `.aiws/changes/<change-id>/review/spec-review.md`（或回退 `.aiws/tmp/review/spec-review.md`）
+   - 运行/收敛 `$ws-quality-review`，落盘 `.aiws/changes/<change-id>/review/quality-review.md`（或回退 `.aiws/tmp/review/quality-review.md`）
    - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
 5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径