@aipper/aiws-spec 0.0.24 → 0.0.25

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

@@ -18,6 +18,30 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 - 未运行不声称已运行；验证命令要写清“预期结果”
 - 若存在 `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 个关键澄清问题（不要猜）。
@@ -66,7 +90,7 @@ fi
    - `Bindings`：`Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
    - `Goal`：要达成什么
    - `Non-goals`：明确不做什么（避免 scope creep）
-   - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
+   - `Scope`：默认写成 `## Scope` 或 `## 影响范围（Scope）`，并包含 `### In Scope` / `### Out of Scope`；`In Scope` 下列出允许修改的文件/目录清单（支持 glob，不确定就写 `TBD` 并说明如何确定）
    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
    - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）

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

@@ -14,6 +14,26 @@ description: 计划质检（执行前检查计划是否过长/跑偏，并给出
 - 已执行过 `$ws-plan`，且准备开始编码
 - 或用户反馈“计划太长/容易跑偏”，需要先压缩并对齐
 
+阶段定位：
+- planning gate；负责在编码前检查计划是否满足 change 严格契约。
+
+必需输入：
+- 当前 `plan/...`
+- `changes/<change-id>/proposal.md`
+- 当前 change 上下文
+
+必需输出：
+- `Quality gate:` pass/fail
+- `Fix list:` 最小修正项
+- `Next:` 通过则 `$ws-dev`，未通过则继续修正并复跑
+
+阻断条件：
+- 无法定位当前 change 或计划文件
+- `aiws change validate <change-id> --strict` 未通过
+
+完成判定：
+- 计划满足严格门禁，且后续实现可以在不补需求/补绑定的情况下直接开始。
+
 执行步骤（建议）：
 1) 先运行 `$ws-preflight`。
 2) 识别 change 上下文：

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

@@ -7,6 +7,29 @@ description: 预检（提交前快速检查与建议）
 
 目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
 
+阶段定位：
+- workflow 入口阶段；负责判断当前仓库是否具备继续执行其它 `ws-*` 阶段的前置条件。
+
+必需输入：
+- 当前项目根目录候选路径
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Missing:` 缺失项
+- `Key rules:` 3-8 条约束摘要
+- `Next:` 若真值齐全，建议进入 `$ws-plan` 或 `$ws-dev`；若缺失，建议先 `aiws init .`
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+
+完成判定：
+- 使用者已经知道当前仓库能否继续进入后续阶段，以及必须遵守的约束与下一步入口。
+
 执行步骤（强制）：
 1) 定位项目根目录：
    - 优先：`git rev-parse --show-toplevel`

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

@@ -0,0 +1,56 @@
+---
+name: ws-quality-review
+description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动的行为正确性、边界条件、测试覆盖和实现质量
+- 把“代码/行为层 findings”优先落盘到 `changes/<change-id>/review/quality-review.md`
+
+阶段定位：
+- review 子 gate；负责实现质量、行为回归与验证覆盖审查。
+
+必需输入：
+- 当前 `git diff`
+- 已执行的验证结果
+- 相关代码 / 配置 / 测试文件
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 review 文件
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/quality-review.md` 或回退 `.agentdocs/tmp/review/quality-review.md`
+- `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
+- `下一步（Next）:` 最小修复项与回归命令
+
+阻断条件：
+- 没有可审改动
+- 没有任何验证上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 quality review 证据，且 findings / 测试缺口 / next 明确。
+
+步骤（建议）：
+1) 先读取 `git diff`、验证结果与相关代码。
+2) 检查：
+   - 行为是否可能回归
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑改动
+   - 是否存在明显复杂度、耦合、可维护性或性能问题
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是质量 / 回归 review，不替代 requirements / gate review。
+- 若发现流程、归因、evidence 缺口，转交给 `$ws-spec-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

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

@@ -7,15 +7,39 @@ description: 评审（提交前审计与证据落盘）
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
 
+阶段定位：
+- review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
+
+必需输入：
+- 当前 `git status` / `git diff`
+- 已执行的验证结果
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前 `change/<change-id>` 上下文（若能识别）
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
+
+必需输出：
+- 审计文件：`changes/<change-id>/review/codex-review.md` 或回退 `.agentdocs/tmp/review/codex-review.md`
+- `主要风险（Top risks）:` 3-8 条
+- `下一步（Next）:` 最小修复清单 + 最小验证命令
+
+阻断条件：
+- 没有可审计的改动或验证上下文
+- 审计证据无法写盘
+
+完成判定：
+- 审计证据已落盘，主要风险和下一步已明确，可作为 commit/deliver 前置输入。
+
 步骤（建议）：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
 2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据
    - 是否维护了 `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` 时使用）
+   - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
 4) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）

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

@@ -0,0 +1,57 @@
+---
+name: ws-spec-review
+description: 规范审查（requirements / plan / evidence / gate 完整性）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动是否满足真值文件、change 绑定、证据路径和 gate 完整性要求
+- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `changes/<change-id>/review/spec-review.md`
+
+阶段定位：
+- review 子 gate；负责 requirements / plan / evidence / workflow gate 完整性审查。
+
+必需输入：
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 当前 `git diff`
+- 若存在：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/spec-review.md` 或回退 `.agentdocs/tmp/review/spec-review.md`
+- `阻断项（Blockers）:` requirements 归因 / gate / evidence 缺口
+- `下一步（Next）:` 修复项与最小验证命令
+
+阻断条件：
+- 无法定位项目根或真值文件
+- 无法判断当前 change / 归因上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 spec review 证据，且明确指出 blocker / warning / next。
+
+步骤（建议）：
+1) 先运行 `$ws-preflight`。
+2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+   - 当前改动能否归因到 `Req_ID` / `Problem_ID`
+   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否与改动保持一致
+   - 是否存在越界目录改动、危险操作、未声明的非目标扩张
+   - 是否已经准备好可复现验证入口
+3) 把结论落盘到：
+   - 默认：`changes/<change-id>/review/spec-review.md`
+   - 回退：`.agentdocs/tmp/review/spec-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `阻断项（Blockers）:`
+   - `警告（Warnings）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是 spec / gate review，不是代码质量 review。
+- 若发现实现质量或回归问题，转交给 `$ws-quality-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

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

@@ -0,0 +1,59 @@
+---
+name: ws-verify-before-complete
+description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
+- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+
+阶段定位：
+- 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。
+- 不执行破坏性命令。

package/templates/workspace/.claude/commands/using-aiws.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:using-aiws -->
+# using aiws
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 把当前任务先路由到正确的 AIWS workflow，而不是直接跳进实现。
+
+执行建议：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+2) 若缺失任一真值文件：先 `/ws-preflight`，必要时运行 `aiws init .`，不要继续实现。
+3) 若任务意图、归因或验证入口不明确：先提 1-3 个关键澄清问题并停止。
+4) 路由规则：
+   - 需求/验收/合同变更：`/ws-req-review`
+   - 中大型实现或需要 change/worktree：`/ws-plan`
+   - 小步明确实现：`/ws-dev`
+   - 评审/审计：`/ws-review`
+   - finish / merge / push / cleanup：`/ws-finish`
+   - handoff / archive summary：`/ws-handoff`
+5) 输出 `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
+6) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。
+<!-- AIWS_MANAGED_END:claude:using-aiws -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

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

package/templates/workspace/.claude/commands/ws-spec-review.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-spec-review -->
+# ws spec review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+   - 当前改动是否能归因到 `Req_ID` / `Problem_ID`
+   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否保持一致
+   - 是否存在越界改动、危险操作或缺失 gate
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/spec-review.md`
+   - 回退：`.agentdocs/tmp/review/spec-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `阻断项（Blockers）:`
+   - `警告（Warnings）:`
+   - `下一步（Next）:`
+<!-- AIWS_MANAGED_END:claude:ws-spec-review -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-verify-before-complete.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-verify-before-complete -->
+# ws verify before complete
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 `/ws-finish` 或 `/ws-handoff` 前检查双审查、validate stamp 与 evidence 是否齐全。
+
+步骤（建议）：
+1) 检查以下最小 gate：
+   - `changes/<change-id>/review/spec-review.md`
+   - `changes/<change-id>/review/quality-review.md`
+   - `.agentdocs/tmp/aiws-validate/*.json`
+2) 若存在 `changes/<change-id>/evidence/`，检查 review / validate / collaboration summary 是否已收敛。
+3) 将结果落盘到：
+   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
+   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `结论（Result）: pass|fail`
+   - `缺失项（Missing）:`
+   - `下一步（Next）:`
+<!-- AIWS_MANAGED_END:claude:ws-verify-before-complete -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/skills/p-aiws-change-archive/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: p-aiws-change-archive
+description: 私有：归档变更工件（会先做严格校验并生成 handoff.md）
+---
+
+目标：
+- 将 `changes/<change-id>/` 归档到 `changes/archive/<YYYY-MM-DD>/...`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "$change_id"
+else
+  npx @aipper/aiws change archive "$change_id"
+fi
+```
+
+说明：
+- `archive` 默认会先跑严格校验并要求 tasks 全部勾选
+- `--force` 会绕过部分门禁（不推荐）
+- 归档后会生成交接文档：`changes/archive/<date>-<change-id>/handoff.md`

package/templates/workspace/.claude/skills/p-aiws-change-finish/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: p-aiws-change-finish
+description: 私有：安全合并 change/<change-id> 回目标分支（默认 fast-forward）
+---
+
+目标：
+- 将 `change/<change-id>` fast-forward 合并回目标分支，减少手输分支名导致的错误
+
+执行（在目标分支所在 worktree 的仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "$change_id"
+else
+  npx @aipper/aiws change finish "$change_id"
+fi
+```
+
+说明：
+- 默认等价于：`git merge --ff-only change/<change-id>`
+- 若你当前就在 `change/<change-id>` 分支上，`finish` 会尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch` 作为目标分支
+- 若无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`

package/templates/workspace/.claude/skills/p-aiws-change-list/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-change-list
+description: 私有：列出 changes 工件（只读）
+---
+
+目标：
+- 列出当前仓库的变更工件与状态
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change list
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change list
+else
+  npx @aipper/aiws change list
+fi
+```

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

@@ -0,0 +1,26 @@
+---
+name: p-aiws-change-new
+description: 私有：创建 changes/<change-id> 工件
+---
+
+目标：
+- 创建 `changes/<change-id>/` 工件目录与基础文件（proposal/tasks/可选 design）
+
+要求：
+- `change-id` 必须是 kebab-case：`^[a-z0-9]+(-[a-z0-9]+)*$`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change new "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change new "$change_id"
+else
+  npx @aipper/aiws change new "$change_id"
+fi
+```
+
+可选参数：
+- `--title <title>`：写入标题
+- `--no-design`：不生成 design.md

package/templates/workspace/.claude/skills/p-aiws-change-next/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: p-aiws-change-next
+description: 私有：给出下一步建议（只读）
+---
+
+目标：
+- 基于当前仓库与 changes 工件状态，输出最小下一步建议
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change next "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change next "$change_id"
+else
+  npx @aipper/aiws change next "$change_id"
+fi
+```

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

@@ -0,0 +1,33 @@
+---
+name: p-aiws-change-start
+description: 私有：切分支并初始化变更工件（可选安装 hooks）
+---
+
+目标：
+- 切到分支 `change/<change-id>` 并初始化 `changes/<change-id>/` 工件
+  - 若检测到 `.gitmodules`（git submodules），默认优先使用 `--worktree`（失败则回退为 `--no-switch`），避免切走 superproject 分支导致 submodule 状态混乱
+
+要求：
+- 需要 git 仓库；若不是 git 仓库先 `git init`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change start "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change start "$change_id"
+else
+  npx @aipper/aiws change start "$change_id"
+fi
+```
+
+可选参数：
+- `--hooks`：同时执行 `aiws hooks install .`
+- `--title <title>`：写入标题
+- `--no-design`：不生成 design.md
+- `--switch`：显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义）
+- `--no-switch`：不切换当前分支（仅确保 `change/<change-id>` 分支存在并初始化工件）；适用于 superproject + submodule 场景
+- `--worktree`：用 `git worktree` 创建独立工作区并在其中 checkout `change/<change-id>`（推荐用于 superproject + submodule）
+  - `--worktree-dir <path>`：覆盖 worktree 目录
+  - `--submodules`：在 worktree 内执行 `git submodule update --init --recursive`

package/templates/workspace/.claude/skills/p-aiws-change-status/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: p-aiws-change-status
+description: 私有：查看单个变更工件状态（只读）
+---
+
+目标：
+- 查看指定 `change-id` 的工件状态与下一步建议
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change status "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change status "$change_id"
+else
+  npx @aipper/aiws change status "$change_id"
+fi
+```

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

@@ -0,0 +1,19 @@
+---
+name: p-aiws-change-sync
+description: 私有：同步真值基线到 changes/<change-id>（写入 .ws-change.json）
+---
+
+目标：
+- 将当前真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）的 hash 快照同步到 `changes/<change-id>/.ws-change.json`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change sync "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change sync "$change_id"
+else
+  npx @aipper/aiws change sync "$change_id"
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-templates-init/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-change-templates-init
+description: 私有：在仓库内初始化 change templates（写入 changes/templates）
+---
+
+目标：
+- 初始化 `changes/templates/`（用于在仓库内自定义 proposal/tasks/design 模板）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates init
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates init
+else
+  npx @aipper/aiws change templates init
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-templates-which/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-change-templates-which
+description: 私有：查看当前 change templates 来源（只读）
+---
+
+目标：
+- 输出当前仓库 change templates 的解析来源与路径（用于排查模板来自哪里）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates which
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates which
+else
+  npx @aipper/aiws change templates which
+fi
+```