@aipper/aiws-spec 0.0.24 → 0.0.26

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

@@ -0,0 +1,17 @@
+---
+name: ws-req-contract-sync
+description: 合同同步（requirements 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`

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

@@ -0,0 +1,12 @@
+---
+name: ws-req-contract-validate
+description: 合同校验（requirements contract validate）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议

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

@@ -0,0 +1,28 @@
+---
+name: ws-req-flow-sync
+description: Flow 同步（生成 api-flow 与场景执行合同）
+---
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `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`：提示用户先运行 `$aiws-init`（默认会安装 optional tools），或执行：
+```bash
+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
+```
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`

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

@@ -0,0 +1,32 @@
+---
+name: ws-req-review
+description: 需求评审（对齐真值与验收）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `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`。

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

@@ -0,0 +1,57 @@
+---
+name: ws-review
+description: 评审（提交前审计与证据落盘）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore` / `librarian`，优先借用这些 agent 做 review。
+- `@oracle` 优先负责独立审查与 findings；`@explore` 用于补 diff 影响面；`@librarian` 用于补 requirements / docs / 依赖上下文。
+- 主 agent 必须负责把 findings 收敛并落盘，不要把子 agent 输出直接当最终 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`，输出约束摘要。
+   - 若检测到 oMo：优先让 `@oracle` 做独立审查；必要时再让 `@explore` / `@librarian` 补上下文。
+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 条（高→低）
+   - `下一步（Next）:` 最小修复清单 + 最小验证命令
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+- 若 oMo agent 不可用，回退为当前 agent 本地 review，不阻断流程。

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

@@ -0,0 +1,23 @@
+---
+name: ws-rule
+description: 规则（解释项目规则与边界）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+安全规则（强制）：
+- 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+- 不执行破坏性命令。
+
+工作流：
+1) 先做 preflight；若缺失 `AI_PROJECT.md`：提示用户先 `$ws-migrate`（或 `$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`

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

@@ -0,0 +1,64 @@
+---
+name: ws-spec-review
+description: 规范审查（requirements / plan / evidence / gate 完整性）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动是否满足真值文件、change 绑定、证据路径和 gate 完整性要求
+- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `changes/<change-id>/review/spec-review.md`
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `librarian`，优先借用它们做 spec / gate 审查。
+- `@oracle` 优先负责 requirements / gate / evidence 独立审查；`@librarian` 负责补文档、规范、依赖与路径真值。
+- 主 agent 负责把 blocker / warning / next 收敛到最终 review 文件。
+
+阶段定位：
+- 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`。
+   - 若检测到 oMo：优先让 `@oracle` 做 spec review 草稿；需要补规范上下文时再调用 `@librarian`。
+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。
+- 不执行破坏性命令。
+- 若 oMo agent 不可用，回退为当前 agent 本地 spec review。

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

@@ -0,0 +1,65 @@
+---
+name: ws-submodule-setup
+description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch；减少 detached 与人为差异）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`，让 `ws-pull` / `ws-finish` 能确定性地“挂回分支/fast-forward push”，避免 origin 多分支时靠猜导致偏差。
+- 该变更是 **superproject 的团队真值**：需要提交 `.gitmodules`。
+
+安全约束（强制）：
+- 不自动提交、不自动 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
+```
+
+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

@@ -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/AGENTS.md

@@ -5,36 +5,80 @@
 3) `AI_WORKSPACE.md`（运行/测试入口真值）
 4) `changes/README.md`（变更工件流程与归档）
 
-协作约束（建议最小集）：
-- 每次变更使用分支 `change/<change-id>`，并维护 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
-- 启用本机门禁（推荐）：`aiws hooks install .`（或手工：`git config core.hooksPath .githooks`；`git commit`/`git push` 会自动跑 `aiws validate .`）
-- 启用 hooks 后，`.githooks/commit-msg` 默认提示优先使用中文 commit message；如需强制，可执行：`git config aiws.commitMessagePolicy strict`
-- 提交前校验（强制门禁）：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
-- Codex（推荐）：本仓库内置 repo skills：`.agents/skills/`（可显式 `$ws-dev`，也可隐式套用工作流）
-- Codex skills 命名约定：`ws-*` 为常用链路入口；`p-*` 为私有原子入口（一般不需要直接调用）。
-- Codex skills（常用，一句话说明）：
-  - `$ws-preflight`：预检（读取真值文件并输出约束摘要）
-  - `$ws-submodule-setup`：子模块分支对齐（写入 `.gitmodules` 的 `submodule.<name>.branch`）
-  - `$ws-plan`：规划（生成可落盘 `plan/` 工件；供 `$ws-dev` 执行）
-  - `$ws-plan-verify`：计划质检（执行前检查计划是否过长/跑偏）
-  - `$p-tasks-plan`：原子：tasks 同步（从 `changes/<id>/tasks.md` 生成 `update_plan` payload）
-  - `$ws-dev`：开发（按需求实现并验证；适用于任何需要修改代码/配置的任务）
-  - `$ws-bugfix`：缺陷修复（禅道 MCP 拉单 + 图片证据落盘 + `issues/fix_bus_issues.csv` 汇总）
-  - `$ws-pull`：拉取并对齐 submodules（尽量避免 detached；减少人为差异）
-  - `$ws-push`：推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
-  - `$ws-review`：评审（提交前审计；证据优先落盘到 `changes/<change-id>/review/`）
-  - `$ws-commit`：提交（先审计/门禁再 commit；submodule 感知）
-  - `$ws-handoff`：交接（归档后生成/查看 `changes/archive/.../handoff.md`，便于跨会话接力）
-  - `$p-aiws-init`：初始化工作区（生成真值文件与门禁）
-  - `$p-aiws-validate`：校验工作区（漂移检测 + 门禁）
-  - `$p-aiws-hooks-install`：启用 git hooks 门禁（`core.hooksPath=.githooks`）
-  - `$p-aiws-change-new`：创建 `changes/<change-id>` 工件
-- Codex CLI（推荐，可选）：安装全局 skills：`npx @aipper/aiws codex install-skills`（写入 `~/.codex/skills/` 或 `$CODEX_HOME/skills`）
-- Codex CLI（遗留，可选）：安装全局 prompts：`npx @aipper/aiws codex install-prompts`（写入 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`；prompts 已 deprecated）
-- 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等
-
-如果缺文件：运行 `npx @aipper/aiws init`（或 `aiws init`）。
-（如你仍在使用 dotfiles 的 `ws` wrappers，也可用 `ws init/ws migrate`；但本模板默认不依赖 dotfiles。）
+最小协作约束：
+- 不确定先跑 `/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 里直接切分支。
+- 提交前执行 `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-plan`：建立 `change/<change-id>` 绑定，落盘 `plan/...`，明确 Verify / Risks / Evidence。
+- `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 + 协同工件模式。
+- `ws-review`：对当前改动做通用审计；高风险或准备交付时，继续细化到 `ws-spec-review` + `ws-quality-review`。
+- `ws-spec-review`：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
+- `ws-quality-review`：审查行为回归、边界条件、测试覆盖与实现质量。
+- `ws-commit`：串联 review + validate stamp + commit message 确认；不跳过 hooks。
+- `ws-verify-before-complete`：在 finish / handoff 前检查双审查、validate stamp 与交付证据是否齐全。
+- `ws-deliver` / `ws-finish`：做交付收尾、fast-forward 合并、submodule 感知 push，并在完整 finish 后自动归档。
+- `ws-handoff`：查看/补充归档后的 handoff，给下一次会话或下一位协作者接力。
+
+阶段产物（最少）：
+- planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
+- implementation：代码 / 配置改动 + Verify 命令记录
+- collaboration：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`
+- review：`changes/<change-id>/review/...` 或回退 `.agentdocs/tmp/review/...`
+- validate：`.agentdocs/tmp/aiws-validate/*.json`
+- handoff / archive：`changes/<change-id>/evidence/...`、`changes/archive/.../handoff.md`
+
+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
+- 常用手动入口继续保留在 `.opencode/commands/`（migration window 内 `.opencode/command/` 也会保留）；直接使用 `/ws-*`
+- 若你不确定当前任务该先 plan、dev、review 还是 finish：先用 `/using-aiws`
+- `/ws-preflight`：读取真值文件并输出约束摘要
+- `/ws-plan` / `/ws-plan-verify`：先生成计划，再做执行前质检
+- `/ws-dev`：常规实现/改配置/改测试
+- `/ws-dev-lite`：小问题直修；若复杂度升高，立刻回到 `/ws-dev` 或 `/ws-plan`
+- `/ws-delegate`：按 AIWS 委托合同拆分子任务，并优先借用 oMo agent
+- `/ws-bugfix`：缺陷修复 + 证据落盘 + CSV 汇总
+- `/ws-review` / `/ws-commit`：提交前审计、门禁与 commit
+- `/ws-spec-review` / `/ws-quality-review`：高风险改动建议显式拆成流程审查 + 质量审查
+- `/ws-verify-before-complete`：finish / handoff 前检查双审查和 validate/evidence
+- `/ws-finish` / `/ws-deliver`：交付收尾（fast-forward / submodule 感知）
+- `/ws-pull` / `/ws-push` / `/ws-submodule-setup`：submodule 场景辅助
+- `/p-aiws-*` 为底层原子入口；模板会同时写入 `.opencode/commands/` 与 `.opencode/command/`，一般不需要直接调用
+
+Claude Code（如果你主要用 Claude Code）：
+- native skills 在 `.claude/skills/`；command-style 兼容入口保留在 `.claude/commands/`
+- 常用链路可按 `ws-*` / `p-aiws-*` 理解；native skills 与 compatibility commands 指向同一套 AIWS workflow
+- 若你不确定当前任务该走哪个阶段：先用 `/using-aiws`
+- 高风险改动或准备 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-review` / `$ws-spec-review` / `$ws-quality-review` / `$ws-commit`
+- `$ws-verify-before-complete` / `$ws-finish` / `$ws-deliver`
+- `$ws-pull` / `$ws-push` / `$ws-submodule-setup`
+- 其它入口见 `.agents/skills/`：`ws-*` 为常用链路；`p-*` 为底层原子入口，一般不需要直接调用
+
+Codex 全局入口（可选）：
+- `npx @aipper/aiws codex install-skills`（推荐；安装全局 skills）
+- `npx @aipper/aiws codex install-prompts`（遗留兼容；prompts 已 deprecated）
+
+缺文件或模板漂移时：
+- `npx @aipper/aiws init`（初始化）
+- `npx @aipper/aiws update`（按模板更新托管内容）
 <!-- AIWS_MANAGED_END:agents -->
 
 你可以在本段下方追加项目自定义说明；`aiws update` 不会改动托管块以外内容。

package/templates/workspace/AI_PROJECT.md

@@ -3,7 +3,7 @@
 <!-- AIWS_MANAGED_BEGIN:ai-project:core -->
 <!-- AI_PROJECT_VERSION: 2 -->
 
-本文件用于在**具体项目/工作区**内统一 Codex / Claude / OpenCode / iFlow 的执行约束与协作方式，避免多套规则各写一份导致漂移。
+本文件用于在**具体项目/工作区**内统一 Codex / Claude / OpenCode 的执行约束与协作方式，避免多套规则各写一份导致漂移。
 
 定位：
 - `REQUIREMENTS.md`：定义“要做什么/验收是什么”（需求真值）

package/templates/workspace/AI_WORKSPACE.md

@@ -32,7 +32,7 @@
 
 <!-- AIWS_MANAGED_BEGIN:ai-workspace:core -->
 
-本文件描述“AI Workspace（多子项目工作区）”的结构与运行方式，供 Codex / Claude / OpenCode / iFlow 共同读取。
+本文件描述“AI Workspace（多子项目工作区）”的结构与运行方式，供 Codex / Claude / OpenCode 共同读取。
 
 ## 1) 目录发现规则
 

package/templates/workspace/changes/README.md

@@ -15,11 +15,22 @@ changes/
     proposal.md
     design.md        # 可选
     tasks.md
+    analysis/        # 可选：外部/子 agent 的分析结论（只读输入）
+    patches/         # 可选：外部/子 agent 的 patch 草案（不自动应用）
+    review/          # 可选：多个 reviewer 的审查结果
+    evidence/        # 推荐：交付前收敛出的持久证据
     .ws-change.json
   archive/
     YYYY-MM-DD-<change-id>/
 ```
 
+协同工件约定：
+- `analysis/`：存放委托分析报告、调研结论、备选方案。默认视为“只读输入”，不要把它当作已实施结果。
+- `patches/`：存放 patch / diff 草案。主 agent 或人工必须先审查，再决定是否应用；不要把该目录内容视为已经进代码库。
+- `review/`：允许多名 reviewer 并行落盘，例如 `codex-review.md`、`reviewer-a.md`、`reviewer-b.md`。
+- `evidence/`：存放 validate 总结、delivery summary、collaboration summary 等可持久引用的交付证据。
+- `aiws change new <change-id>` 会预创建以上目录，减少临时约定漂移。
+
 常用命令（推荐使用 `aiws`；不依赖 dotfiles）：
 - `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录；若检测到 `.gitmodules` 则默认优先使用 worktree，失败则回退为不切分支，避免 submodule 状态混乱）
 - `aiws change start <change-id> --no-switch`（superproject + submodule 场景：不切分支，仅准备 `change/<change-id>` 分支与工件目录）
@@ -28,18 +39,19 @@ changes/
   - 可选：`--worktree-dir <path>` 覆盖 worktree 目录
   - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`
 - `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；含 submodule 的 worktree 会因 Git 原生限制在 clean-check 后内部走 `git worktree remove --force`）
+- `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 new <change-id>`
 - `aiws change list`
 - `aiws change status <change-id>`
 - `aiws change next <change-id>`
 - `aiws change validate <change-id>`
 - `aiws change sync <change-id>`
-- `aiws change archive <change-id>`
+- `aiws change archive <change-id>`（手工恢复 / 历史兼容入口；标准链路一般不需要单独执行）
+- `aiws change evidence <change-id>`（收敛 review / validate / collaboration summary 到 `changes/<id>/evidence/`）
 
 Active change（推荐，团队共享）：
 - 使用分支名声明当前变更：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync|archive`
+- 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync`
 
 计划质量门（推荐，执行前）：
 - 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支 / worktree，再在该上下文内写 `plan/...`）
@@ -62,7 +74,10 @@ Active change（推荐，团队共享）：
 
 Hooks/CI（推荐，硬约束）：
 - 工作区会安装 `.githooks/{commit-msg,pre-commit,pre-push}`：
-  - `commit-msg`：默认提示优先使用中文 commit message；若执行 `git config aiws.commitMessagePolicy strict`，则会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+  - `commit-msg`：默认行为按仓库角色区分
+    - superproject / root 仓库（存在 `.gitmodules`）：默认 `off`，允许自由 commit message
+    - submodule / 普通仓库：默认 `warn`，提示优先使用中文 commit message
+    - 若执行 `git config aiws.commitMessagePolicy strict`，则会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
   - `pre-commit` / `pre-push`：默认执行 `aiws validate .`
 - 还会安装门禁脚本（`tools/ws_change_check.py`、`tools/requirements_contract.py`）。
 - **启用 hooks 需要本地配置**（不会自动提交到 git）：
@@ -76,3 +91,9 @@ Hooks/CI（推荐，硬约束）：
   - 完成后在主工作区（例如 `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`
+
+协同交付建议：
+- 委托分析先落到 `changes/<id>/analysis/`，由主 agent 在 `ws-review` 或 `review/*.md` 中收敛结论。
+- patch 草案先落到 `changes/<id>/patches/`，未经审查不要直接应用。
+- 交付前建议执行：`aiws change evidence <change-id>`，让 `delivery-summary` 与 `collaboration-summary` 一起落到 `changes/<id>/evidence/`。
+- finish 自动归档后生成的 `handoff.md` 会包含协同工件摘要，便于下一次会话继续接力。

package/templates/workspace/changes/templates/proposal.md

@@ -45,6 +45,20 @@
 
 - <!-- WS:TODO 逐条写清要改什么（行为/接口/数据/配置）；BREAKING 请标注 -->
 
+## 协同与委托（可选）
+
+- `analysis/`：
+  - <!-- WS:TODO 如需委托分析，写明预计产物；例如 `changes/<change-id>/analysis/research-a.md` -->
+- `patches/`：
+  - <!-- WS:TODO 如需外部 patch 草案，写明预计文件；例如 `changes/<change-id>/patches/fix-a.patch` -->
+- `review/`：
+  - <!-- WS:TODO 如需多审查者，写明 reviewer 文件命名或汇总策略 -->
+
+> 规则：
+> - `analysis/` 产物默认只作为输入依据，不等于实现完成。
+> - `patches/` 中的 patch 草案不自动应用，必须经主 agent 或人工审查。
+> - 交付前建议把协同结果收敛到 `review/` 或 `evidence/`，并回填 `Evidence_Path`。
+
 ## 影响范围（Scope）
 
 ### In Scope（本次改动范围）
@@ -95,3 +109,4 @@
 - 证据落盘（推荐双层）：
   - 持久（建议入库）：`changes/<change-id>/evidence/...`（例如 validate 总结、review 总结、关键日志摘要）
   - 临时（可忽略入库）：`.agentdocs/tmp/...`（例如 `aiws validate . --stamp` 的 JSON）
+  - 协同（按需）：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`

package/templates/workspace/changes/templates/tasks.md

@@ -25,6 +25,12 @@
 - [ ] 2.1 <!-- WS:TODO -->
 - [ ] 2.2 <!-- WS:TODO -->
 
+## 2A. 协同（可选）
+
+- [ ] 2A.1 若使用委托分析：把结果落盘到 `changes/{{CHANGE_ID}}/analysis/`
+- [ ] 2A.2 若使用 patch 草案：把结果落盘到 `changes/{{CHANGE_ID}}/patches/`，并记录是否采用
+- [ ] 2A.3 若存在多审查者：把审查结果落盘到 `changes/{{CHANGE_ID}}/review/`
+
 ## 3. 验证（必须可复现）
 
 - [ ] 3.1 <!-- WS:TODO 写具体命令（来自 AI_WORKSPACE.md） -->
@@ -33,5 +39,6 @@
 ## 4. 交付与归档
 
 - [ ] 4.1 证据落盘到 `.agentdocs/tmp/...`（报告/日志/请求响应等）
-- [ ] 4.2 交叉审计（可选但推荐）：在 AI 工具内运行 `/ws-review`（或按 `AI_PROJECT.md` 手工审计）
-- [ ] 4.3 归档：`aiws change archive {{CHANGE_ID}}`
+- [ ] 4.2 生成持久证据：`aiws change evidence {{CHANGE_ID}}`
+- [ ] 4.3 交叉审计（可选但推荐）：在 AI 工具内运行 `/ws-review`（或按 `AI_PROJECT.md` 手工审计）
+- [ ] 4.4 收尾：`aiws change finish {{CHANGE_ID}} --push`（成功后自动归档并生成 handoff）