@aipper/aiws-spec 0.0.24 → 0.0.25

package/templates/workspace/.opencode/commands/ws-req-change.md

@@ -0,0 +1,45 @@
+---
+description: 需求变更：更新 REQUIREMENTS 并同步执行合同
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-change -->
+# ws req change
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `REQUIREMENTS.md` + 追加 `requirements/CHANGELOG.md`），并同步/校验执行合同 `requirements/requirements-issues.csv`。
+
+步骤（必须按顺序）：
+1) 读取：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`requirements/CHANGELOG.md`（缺失则创建目录与文件）。
+2) 先产出“拟变更方案”（不要立刻写文件）：
+   - 变更摘要（1–5 条）
+   - 影响范围（API/鉴权/字段/状态码/测试边界）
+   - 回滚思路（1–2 条）
+3) 对比与冲突检查（强制，不写文件）：
+   - 对比“变更前 vs 拟变更后”的差异清单（新增/删除/语义变化）
+   - 整理潜在冲突/不确定点（只列“最可能影响验收/实现”的，避免噪音）
+4) 逐条澄清（强制，避免一次问完）：
+   - 若存在潜在冲突/不确定点：**本轮只问 1 个**最高优先级问题（给出 2–4 个可选答案或二选一），然后停止，等待用户回复；不要继续问下一题，也不要写文件。
+   - 收到用户回复后：更新“拟变更方案”，回到步骤 3) 重新对比，直至没有未决问题。
+5) 强制停下来让用户确认：是否继续落盘？(Y/N)
+6) 用户确认 Y 后再写入：
+   - 更新 `REQUIREMENTS.md`（只保留当前有效版本，不在此堆历史）
+   - 追加 `requirements/CHANGELOG.md`
+7) 同步/补齐需求执行合同（强制，自动处理 FlowSpec 有/无两种情况）：
+   - `python3 tools/requirements_contract_sync.py --workspace .`
+   - 说明：若 `REQUIREMENTS.md` 中不存在 FlowSpec（或 flows 为空），该命令只会确保 `requirements/requirements-issues.csv` 表头存在并给出 WARN（这是预期行为，不要当成失败）。
+8) 校验需求执行合同（强制）：`python3 tools/requirements_contract.py validate`
+9) 同步场景合同（可选，但若存在 FlowSpec 则强烈建议自动执行）：
+   - 若 `REQUIREMENTS.md` 同时包含 `<!-- FLOW_SPEC_BEGIN -->` 与 `<!-- FLOW_SPEC_END -->`：运行 `/ws-req-flow-sync`
+   - 否则：跳过，并提示用户“可以先不维护 FlowSpec；后续需要场景回归时再补”
+
+输出必须包含：
+- 本次更新的文件清单（路径）
+- 回滚方案（如何撤销本次需求变更）
+- 下一步建议命令
+
+安全：
+- 不打印 `secrets/test-accounts.json`
+- 不引入任何 token/密钥到仓库
+<!-- AIWS_MANAGED_END:opencode:ws-req-change -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-contract-sync.md

@@ -0,0 +1,21 @@
+---
+description: 合同同步：把 REQUIREMENTS FlowSpec 同步到 requirements-issues.csv
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-sync -->
+# ws req contract sync
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+用途：从 `REQUIREMENTS.md` 的 FlowSpec 补齐 `requirements/requirements-issues.csv`（只生成骨架，不猜测完成状态）。
+
+执行（在 workspace 根目录）：
+- `python3 tools/requirements_contract_sync.py --workspace .`
+
+输出要求：
+- 说明新增/更新了多少条
+- 明确下一步：手工补齐 CRUD/Inputs/Outputs/Business_Logic/Tests，并将可开工条目标为 `Spec_Status=READY`
+
+下一步建议：`/ws-req-contract-validate`
+<!-- AIWS_MANAGED_END:opencode:ws-req-contract-sync -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,16 @@
+---
+description: 合同校验：校验 requirements-issues.csv 字段完整性
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-validate -->
+# ws req contract validate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议
+<!-- AIWS_MANAGED_END:opencode:ws-req-contract-validate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,23 @@
+---
+description: Flow 同步：从 REQUIREMENTS 生成 api-flow 与场景执行合同
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-flow-sync -->
+# ws req flow sync
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `REQUIREMENTS.md` 的 FlowSpec 生成：
+- `docs/api-flow.mmd`（简短逻辑图，Mermaid）
+- `issues/server-scenario-issues.csv`（场景执行合同：TODO/DONE/BLOCKED）
+
+执行（在 workspace 根目录）：
+`python3 tools/requirements_flow_gen.py --workspace .`
+
+若缺少工具 `tools/requirements_flow_gen.py`：提示用户先运行 `npx @aipper/aiws init .`（默认会安装 optional tools）。
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`
+<!-- AIWS_MANAGED_END:opencode:ws-req-flow-sync -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-review.md

@@ -0,0 +1,36 @@
+---
+description: 需求评审：对 REQUIREMENTS 做整体 QA（不改文件）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-review -->
+# ws req review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+   - `requirements/CHANGELOG.md`（若存在）
+   - `requirements/requirements-issues.csv`（若存在）
+3) 输出固定结构的报告：
+
+## Requirements QA
+- 结论：是否可进入实现（是/否/有条件）
+- 漂移风险：最容易导致不一致的点
+- 可验收性缺口：缺少输入/输出/错误码/边界/示例的条目
+- 完整性：Non-goals/兼容性/鉴权/重试/并发/观测性/性能
+- 一致性：与 `AI_PROJECT.md` 约束冲突点
+- 可测试性与证据：最小验证命令 + 期望结果 + 证据路径
+- 风险清单：3–8 条
+- 需要澄清的问题：5–12 个（按优先级）
+
+4) 最后询问用户：是否进入需求落盘流程 `/ws-req-change`？(Y/N)
+
+安全：不打印 `secrets/test-accounts.json`。
+<!-- AIWS_MANAGED_END:opencode:ws-req-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-review.md

@@ -0,0 +1,33 @@
+---
+description: 评审：提交前审计改动并落盘证据
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-review -->
+# ws review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `explore` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - 独立审查优先 `@oracle`；diff 影响面优先 `@explore`；规范/文档上下文优先 `@librarian`。
+2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+   - 是否存在越界目录改动/危险操作
+   - 是否有可复现验证命令与证据
+   - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+3) 将审计落盘到（目录不存在则创建）：
+   - 默认：`changes/<change-id>/review/opencode-review.md`
+   - 回退：`.agentdocs/tmp/review/opencode-review.md`（仅在无法确定 `change-id` 时使用）
+4) 回复中输出：
+   - `证据（Evidence）:` 证据文件路径
+   - `主要风险（Top risks）:` 3–8 条（高→低）
+   - `下一步（Next）:` 最小修复清单 + 最小验证命令
+5) 若 oMo 不可用：回退为当前 agent 本地 review，不阻断流程。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-rule.md

@@ -0,0 +1,27 @@
+---
+description: 规则：把口述规则整理并写入 AI_PROJECT.md 托管段
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-rule -->
+# ws rule
+
+     用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+     目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+     安全规则（强制）：
+     - 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+     - 不执行破坏性命令。
+
+     工作流：
+     1) 先运行 `/ws-preflight`；若缺失 `AI_PROJECT.md`：提示用户先 `/ws-migrate` 或运行 `npx @aipper/aiws init .`。
+     2) 写入前创建备份（必须）：
+`ts="$(date +%Y%m%d-%H%M%S)"; mkdir -p .aiws/backups/manual; cp -a AI_PROJECT.md .aiws/backups/manual/AI_PROJECT.md.bak.${ts}`
+     3) 先输出“将写入的规则清单”（3–12 条），并要求用户回复 `CONFIRM` 后再落盘。
+     4) 用户确认后，**仅更新** BEGIN/END 段内内容（合并去重；写成可检查条款：目录白名单/必须验证命令/禁止项/产物要求）。
+     5) 输出必须包含：
+        - 更新了哪些文件（路径）
+        - 回滚方式（恢复备份文件）
+        - 下一步建议：`aiws validate .`
+<!-- AIWS_MANAGED_END:opencode:ws-rule -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,30 @@
+---
+description: 规范审查：requirements / plan / evidence / gate 完整性
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-spec-review -->
+# ws spec review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - requirements / gate / evidence 审查优先 `@oracle`；规范与文档真值补充优先 `@librarian`。
+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）:`
+5) 若 oMo 不可用：回退为当前 agent 本地 spec review。
+<!-- AIWS_MANAGED_END:opencode:ws-spec-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-submodule-setup.md

@@ -0,0 +1,57 @@
+---
+description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-submodule-setup -->
+# ws submodule setup
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`（团队真值），让 `/ws-pull`、`/ws-finish` 能确定性地减少 detached 与人为差异；并使 `aiws validate` 的 submodule 分支门禁通过。
+
+约束：
+- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
+- 不做破坏性命令
+
+步骤（建议）：
+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 让用户选择目标分支（推荐具体分支名；可选 `.` 表示跟随 superproject 分支名）：
+```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)"
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
+```
+
+4) 写入分支配置：
+```bash
+git submodule set-branch --branch <branch-or-dot> <sub_path>
+```
+
+5) 输出 diff 并让用户确认是否提交：
+```bash
+git diff -- .gitmodules
+git status --porcelain
+```
+
+6) 用户确认后提交：
+```bash
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branches"
+```
+<!-- AIWS_MANAGED_END:opencode:ws-submodule-setup -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

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

@@ -0,0 +1,27 @@
+---
+description: 完成前验证：finish / handoff 前检查双审查与 validate/evidence
+---
+<!-- AIWS_MANAGED_BEGIN:opencode: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:opencode:ws-verify-before-complete -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/oh-my-opencode.json.example

@@ -0,0 +1,17 @@
+{
+  "agents": {
+    "planner-sisyphus": {
+      "enabled": true,
+      "replace_plan": false
+    },
+    "librarian": {
+      "enabled": true
+    },
+    "explore": {
+      "enabled": true
+    },
+    "oracle": {
+      "enabled": true
+    }
+  }
+}

package/templates/workspace/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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
+```

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

@@ -0,0 +1,23 @@
+---
+name: p-aiws-change-validate
+description: 私有：校验 changes 工件（可 strict）
+---
+
+目标：
+- 校验 `changes/<change-id>/` 工件完整性、归因与 WS:TODO（用于 hooks/CI）
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate "$change_id" --strict
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate "$change_id" --strict
+else
+  npx @aipper/aiws change validate "$change_id" --strict
+fi
+```
+
+说明：
+- `--strict` 会把 `WS:TODO`/缺少归因视为错误，并启用计划质量门（章节完整、步骤粒度、验证命令与预期）
+- 紧急情况下可用 `--allow-truth-drift`（不推荐）

package/templates/workspace/.opencode/skills/p-aiws-hooks-install/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: p-aiws-hooks-install
+description: 私有：启用 git hooks 门禁（core.hooksPath=.githooks）
+---
+
+目标：
+- 为当前 git 仓库启用 aiws 门禁 hooks（`git commit`/`git push` 自动跑 `aiws validate .`）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks install .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks install .
+else
+  npx @aipper/aiws hooks install .
+fi
+```
+
+验证（可选）：
+```bash
+git config core.hooksPath
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.opencode/skills/p-aiws-hooks-status/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-hooks-status
+description: 私有：查看当前仓库 hooks 状态（只读）
+---
+
+目标：
+- 输出当前仓库 hooks 状态（不修改文件）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```