@aipper/aiws-spec 0.0.24 → 0.0.25

package/README.md

@@ -12,3 +12,25 @@ npx @aipper/aiws init .
 - `templates/workspace/`：workspace 模板（真值文件、tool-native commands/skills、hooks、门禁脚本等）
 - `docs/spec-contract.md`：模板契约（required/optional、managed markers、tool matrix、`.aiws/manifest.json` 约定）
 - `docs/cli-interface.md`：CLI 行为语义（定义为主）
+- `docs/aiws-governance-positioning.md`：`aiws` 作为工作流治理内核的定位、分层与边界
+- `docs/aiws-bootstrap-routing-design.md`：bootstrap/router 与 `Codex / Claude / OpenCode` 目录对齐设计
+- `docs/superpowers-collaboration-adoption.md`：吸收 `superpowers` 与协同模式的范围、非目标与分阶段路线
+- `docs/workflow-stage-contracts.md`：核心 `ws-*` workflow 的人类可读阶段契约说明（由 JSON 真值生成）
+- `docs/workflow-stage-contracts.json`：dashboard / API 共用的机器可读阶段契约真值
+- `docs/workflow-stage-contracts.schema.json`：阶段契约 JSON 的结构约束
+- `docs/workflow-governance-rules.md`：阶段推断规则的人类可读说明（由 JSON 真值生成）
+- `docs/workflow-governance-rules.json`：`change status/next/dashboard` 共用的机器可读阶段推断规则（含 dual review / finish gate 缺口）
+- `docs/workflow-governance-rules.schema.json`：阶段推断规则 JSON 的结构约束
+- `docs/workflow-router-rules.md`：默认 bootstrap/router 的人类可读说明（由 JSON 真值生成）
+- `docs/workflow-router-rules.json`：`using-aiws` / `ws-router` 共用的机器可读路由规则真值
+- `docs/workflow-router-rules.schema.json`：router 规则 JSON 的结构约束
+- `docs/workflow-review-gates.md`：双审查与完成前验证 gate 的人类可读说明（由 JSON 真值生成）
+- `docs/workflow-review-gates.json`：`ws-spec-review` / `ws-quality-review` / `ws-verify-before-complete` 共用的机器可读 gate 真值
+- `docs/workflow-review-gates.schema.json`：review gate JSON 的结构约束
+- `docs/workflow-delegation-contracts.md`：原生多 agent 委托合同的人类可读说明（由 JSON 真值生成）
+- `docs/workflow-delegation-contracts.json`：原生 delegation 的角色/边界/工件/降级策略真值
+- `docs/workflow-delegation-contracts.schema.json`：delegation contract JSON 的结构约束
+- `docs/opencode-omo-adapter.md`：OpenCode + oh-my-opencode 的适配边界、角色映射与 fallback 约定
+- `docs/opencode-omo-validation-checklist.md`：OpenCode + oMo 的真实项目验收清单（探测、启用、损坏配置、fallback）
+- `templates/workspace/.opencode/oh-my-opencode.json.example`：保守的项目级 oMo agent 建议配置（只覆盖 agents）
+- `docs/collaboration-artifacts.md`：`analysis/patches/review/evidence` 的协同工件目录与生命周期约定

package/docs/aiws-bootstrap-routing-design.md

@@ -0,0 +1,138 @@
+# aiws Bootstrap / Router 与跨工具目录对齐设计
+
+## 目标
+
+把 `aiws` 从“提供一组可显式调用的 `ws-*` 入口”推进到“默认先接管 workflow，再决定进入哪个入口”的治理系统，并先把 `Codex / Claude Code / OpenCode` 的目录真值固定下来，避免后续 bootstrap / router / 安装器继续建立在错误路径假设上。
+
+## 本次查档结论（2026-03-30）
+
+### Claude Code
+
+- 官方文档公开说明的项目级 / 全局级入口是：
+  - skills：`.claude/skills/<skill-name>/SKILL.md` / `~/.claude/skills/<skill-name>/SKILL.md`
+  - 自定义 slash commands（legacy compatible）：`.claude/commands/` / `~/.claude/commands/`
+  - subagents：`.claude/agents/` / `~/.claude/agents/`
+- 官方文档同时说明：`.claude/commands/*.md` 仍然可用，但若 skill 与 command 同名，skill 优先。
+
+### OpenCode
+
+- 官方文档公开说明的 native 目录是：
+  - skills：`.opencode/skills/` / `~/.config/opencode/skills/`
+  - commands：`.opencode/commands/` / `~/.config/opencode/commands/`
+- OpenCode 官方文档同时说明会检测其它 agent 生态目录，包括：
+  - `.agents/skills/`
+  - `.claude/commands/`
+  - `.claude/skills/`
+
+### Codex
+
+- 本次检索到的 OpenAI 官方公开页面没有明确给出 “Codex skills 全局目录”的公开路径说明。
+- 因此，`Codex` 的目录结论需要明确标记为**推断**：
+  - repo-local：`.agents/skills/`
+  - global：`~/.agents/skills/`
+- 这个推断依据是：
+  - 当前 Codex 运行环境与生态使用习惯都以 `.agents/skills/` 为项目内 skills 目录
+  - OpenCode 官方文档也把 `.agents/skills/` 视为兼容可发现目录
+- 在找到 OpenAI 官方公开页面直接写明路径前，不再把 `~/.codex/skills/` 当成长期目录真值。
+
+## 固定下来的目录决策
+
+### 1. repo 内 workflow skill 的目标投影
+
+- `Codex` / agent-compatible：
+  - `.agents/skills/<skill-name>/SKILL.md`
+- `Claude Code` native：
+  - `.claude/skills/<skill-name>/SKILL.md`
+- `OpenCode` native：
+  - `.opencode/skills/<skill-name>/SKILL.md`
+- 设计原则：
+  - workflow instruction 的单一真值仍然留在 `packages/spec/`
+  - 目标仓库可以投影到多个 tool-native 目录
+  - 不能再把 `.agents/skills/` 单独当成覆盖所有工具的唯一目标目录
+
+### 2. Codex 全局 skills 安装目标
+
+- 设计真值改为：`~/.agents/skills/<skill-name>/SKILL.md`
+- 不再把 `~/.codex/skills/` 作为长期默认目录
+- 当前实现若仍写入 `~/.codex/skills/`，视为第一版实现遗留；后续通过单独实现条目迁移
+
+### 3. Claude Code 入口策略
+
+- native workflow skill 目录：
+  - `.claude/skills/<skill-name>/SKILL.md`
+- 如后续确有必要引入 agent 角色：
+  - `.claude/agents/*.md`
+- `.claude/commands/*.md` 继续保留为 legacy compatibility / command-style entrypoint，但不再作为唯一长期真值
+
+### 4. OpenCode 入口策略
+
+- native 真值应记录为：
+  - skills：`.opencode/skills/`
+  - commands：`.opencode/commands/`
+- 由于当前仓库仍有 `.opencode/command/`（单数）遗留，先明确它是**legacy compatibility path**，不再把它当未来默认路径
+- 由于 OpenCode 可兼容读取 `.agents/skills/`，repo 共享 workflow skills 仍保持在 `.agents/skills/`
+
+## Bootstrap / Router 设计
+
+### 设计目标
+
+- 新增一个总入口：`using-aiws` 或 `ws-router`
+- 作用不是替代所有 `ws-*`，而是让任何 coding task 先经过 workflow 路由，再决定进入哪个 skill
+- 这样 `aiws` 才不是 “opt-in workflow toolbox”，而是 “default-routed governance system”
+
+### 路由顺序
+
+1. 先进入 bootstrap：
+   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+2. 识别任务意图：
+   - 规划类 -> `ws-plan`
+   - 实现类 -> `ws-dev` / `ws-execute` / `ws-subagent-dev`
+   - 评审类 -> `ws-review`（后续拆分成 `ws-spec-review` + `ws-quality-review`）
+   - 收尾类 -> `ws-finish`
+   - 交接类 -> `ws-handoff`
+3. 若意图不明确：
+   - 阻断，先澄清任务归因与目标
+
+### Router 真值
+
+- 后续新增一份机器可读真值：
+  - `packages/spec/docs/workflow-router-rules.json`
+- 并生成：
+  - `packages/spec/docs/workflow-router-rules.md`
+  - `packages/spec/docs/workflow-router-rules.schema.json`
+- 路由规则必须落在 `packages/spec/`，而不是散落到某个工具专用 prompt 中
+
+## 对现有实现的修正结论
+
+### 需要被后续实现修正的点
+
+- `aiws codex install-skills` 的默认全局目录应从 `~/.codex/skills` 调整为 `~/.agents/skills`
+- 若后续增加 Claude 全局 skills 安装，目标应是 `~/.claude/skills/`，不是继续只投递到 `~/.claude/commands/`
+- 若后续增加 OpenCode 全局 skills 安装，目标应是 `~/.config/opencode/skills/`
+- OpenCode 的 native commands 路径长期应对齐到 `.opencode/commands`，不再把 `.opencode/command` 当默认真值
+- 需要新增 bootstrap / router 入口，而不是继续完全依赖使用者手工显式调用 `$ws-plan` / `$ws-dev` / `$ws-review`
+
+### 本文档不做的事
+
+- 不在本条中直接修改 CLI 实现
+- 不立即迁移现有模板目录
+- 不把 `aiws` 做成 runtime / daemon / pane orchestration 系统
+
+## 条目拆分与当前状态
+
+1. 目录对齐实现：
+   - Codex 全局 skills 目录迁移
+   - OpenCode native commands 目录迁移
+   - 当前已由 `TOOLING-002G` 落地
+2. workflow bootstrap / router：
+   - `using-aiws`
+   - `workflow-router-rules.json`
+   - 当前已由 `TOOLING-002H` 落地
+3. 执行控制器：
+   - `ws-execute`
+   - `ws-subagent-dev`
+4. 双审查与完成前验证：
+   - `ws-spec-review`
+   - `ws-quality-review`
+   - `ws-verify-before-complete`
+   - 当前已由 `TOOLING-002I` 落地

package/docs/aiws-governance-positioning.md

@@ -0,0 +1,69 @@
+# aiws：工作流治理内核定位
+
+## 一句话定位
+
+`aiws` 不是“把模板分发到 Claude Code / OpenCode / Codex / iFlow 的 CLI 薄封装”，而是以 `packages/spec/` 为单一真值，通过 workflow contracts 统一约束、门禁、协同和证据的 AI workspace 工作流治理系统。
+
+CLI 分发能力依然重要，但它只是治理内核的一层实现，不是产品的全部定义。
+
+## 为什么不能只把 aiws 看成分发器
+
+- 纯分发叙事只能解释“文件写到哪里”，解释不了 `ws-preflight`、`ws-plan`、`ws-review`、`ws-commit`、`ws-finish` 这些 workflow 入口为什么存在。
+- `changes/`、`validate` stamp、review 工件、多工具入口并不是模板副产物，而是治理对象本身。
+- 用户真正需要的是“团队如何被约束并稳定交付”，而不是“某个 prompt 或 skill 被复制到了哪个目录”。
+
+## 分层模型
+
+### 1. 规则真值层
+
+- 单一真值固定在 `packages/spec/`。
+- 真值内容包括模板、文档、manifest、门禁脚本与 workflow 约定。
+- 所有工具入口都应回指这层，而不是各写一套规则。
+
+### 2. 工作流治理层
+
+- 把工作拆成可审计阶段，而不是把 AI 当成自由发挥的聊天窗口。
+- 典型阶段包括：`preflight -> plan -> dev -> review -> commit -> finish / handoff`。
+- 每个阶段都要定义输入、输出、失败条件和回到真值文件的路径。
+
+### 3. 执行 / 分发层
+
+- `@aipper/aiws` CLI 负责把真值层与治理层映射到目标仓库。
+- tool-native files、skills、commands、hooks 都属于这一层的适配器。
+- 这一层应尽量保持“薄”，重点是把治理契约稳定投递到各工具，而不是在工具侧复制业务规则。
+
+### 4. 证据 / 审计层
+
+- `changes/`、`.agentdocs/tmp/`、validate stamp、review 结果都属于交付证据。
+- `aiws` 不只约束“怎么做”，也要约束“做完后留下什么证据”。
+- 有证据，才有回放、复核、审计和交接。
+
+## 设计原则
+
+- `packages/spec/` 是唯一规则真值，不能再平行维护第二套治理规范。
+- 优先定义 workflow contract，再决定命令名、skill 名或工具适配细节。
+- 协同能力要能落盘成工件，而不是只存在于会话上下文。
+- 审查优先看规范与门禁是否满足，再看代码质量与实现技巧。
+- 破坏性动作必须经过显式确认，治理系统不应鼓励“自动越权执行”。
+
+## 与 superpowers、协同运行时的关系
+
+### 吸收什么
+
+- 吸收 `superpowers` 的 workflow-first 思路。
+- 吸收 `superpowers` 用 skill 承载流程约束的做法。
+- 吸收协同模式中的角色分工、委托回传、双审查与交接意识。
+
+### 不吸收什么
+
+- 不把 `aiws` 做成 `claude_code_bridge` 风格的 pane / daemon / runtime orchestration。
+- 不直接 vendoring 整套 `superpowers` hooks、skill 文案和运行时假设。
+- 不让某个单一厂商或单一 agent 形态成为治理内核的前提条件。
+
+## 对外表达
+
+对内和对外都应把 `aiws` 表述为：
+
+“一个以 `packages/spec/` 为真值、通过 workflow contracts 在多 AI 工具中实施约束、门禁、协同与证据管理的治理内核。”
+
+这一定义允许 `aiws` 保持多工具适配能力，同时避免退化成“仅做文件分发”的工具集合。

package/docs/cli-interface.md

@@ -33,7 +33,11 @@
 语义：
 - 在目标仓库根目录写入/补齐模板（默认 `workspace`）。
 - 默认生成 required + optional 文件/目录。
-- 写入/更新 tool-native 文件（默认覆盖 Claude/OpenCode/Codex/iFlow；Codex 为 repo skills：`.agents/skills/`）。
+- 写入/更新 tool-native 文件（默认覆盖 Claude/OpenCode/Codex/iFlow）：
+  - Codex repo skills：`.agents/skills/`
+  - Claude Code native skills + compatibility commands：`.claude/skills/` + `.claude/commands/`
+  - OpenCode native skills + native commands + legacy compatibility commands：`.opencode/skills/` + `.opencode/commands/` + `.opencode/command/`
+  - iFlow commands：`.iflow/commands/`
 - 写入/更新 `.gitignore` 的 aiws 托管块（其余内容保留）。
 - 生成并写入 `.aiws/manifest.json`：
   - 记录 `template_id/spec_version/aiws_version`
@@ -99,8 +103,8 @@
 
 语义：
 - 将模板内的 skills（`templates/<template_id>/.agents/skills/*/SKILL.md`）安装到 Codex 的全局 skills 目录：
-  - 默认：`~/.codex/skills/`
-  - 若设置了 `CODEX_HOME`：`$CODEX_HOME/skills/`
+  - 默认：`~/.agents/skills/`
+  - 若设置了 `CODEX_HOME`：`$CODEX_HOME/.agents/skills/`（仅作为 compatibility/test override）
 - 幂等：重复执行应只更新 AIWS 托管块，不破坏用户在文件托管块外追加的说明。
 - 若目标文件已存在但不含 AIWS 托管块：默认失败（退出码 `2`）；需用户显式 `--force` 才允许覆盖（覆盖前应备份）。
 - 支持预演：`--dry-run` 仅输出将创建/更新/覆盖的 skills 清单，不写入任何文件。
@@ -199,6 +203,47 @@
 接口（仅定义）：
 - `aiws hooks status [path]`
 
+## `aiws dashboard`
+
+语义：
+- 启动本地 Dashboard（不依赖外部服务），聚合 change 状态、质量门结果、证据路径、协同摘要与下一步建议。
+- 数据源：
+  - 当前工作区 `changes/<id>/`
+  - `.agentdocs/tmp/...`
+  - `@aipper/aiws-spec/docs/workflow-stage-contracts.json`（阶段契约真值）
+  - `@aipper/aiws-spec/docs/workflow-governance-rules.json`（阶段推断规则真值）
+  - `@aipper/aiws-spec/docs/workflow-review-gates.json`（dual review / finish gate 真值）
+- 阶段推断约束：
+  - `currentStage/recommendedStage` 必须来自共享 change 状态，而不是 dashboard 单独猜测
+  - 若存在独立 `change/<id>` worktree，优先读取该 worktree 的 `git status`
+  - 若 worktree 元数据已 stale，不应导致 API/UI 失败；应返回 warning 并回退到当前 worktree
+  - 至少区分 `ws-review` / `ws-commit` / `ws-deliver` / `ws-finish` / `ws-handoff`
+- 页面应至少展示：
+  - change 列表、tasks 进度、truth drift、strict blockers
+  - collaboration 摘要（analysis / patches / review / evidence）
+  - review gate 摘要（`spec_review` / `quality_review` / `validate_stamp` / `verify_before_complete`）
+  - next advice（进入 `$ws-dev` / `$ws-deliver` 等）
+  - 当前阶段与推荐下一阶段的契约摘要
+
+接口（仅定义）：
+- `aiws dashboard serve [--host 127.0.0.1] [--port 3456]`
+
+Dashboard API（本地只读）：
+- `GET /api/changes`
+  - 返回 change 状态汇总，包含 `phase`、`collaboration`、`reviewGates`、`nextAdvice`、`governance`
+  - `governance` 至少包含：
+    - `phase`
+    - `currentStage`
+    - `recommendedStage`
+    - `rationale`
+    - `ruleId`
+    - `source`
+    - `warning`（可选；例如 stale worktree metadata）
+- `GET /api/workflow-stages`
+  - 返回从 spec 真值读取的 workflow stage contracts
+- `GET /api/change/<id>/validate?strict=1`
+  - 返回 strict validate 的 JSON 结果（`ok/errors/warnings/groups`）
+
 ## `aiws change`
 
 背景：
@@ -217,6 +262,7 @@
   - `tasks.md`
   - `design.md`（可选；`--no-design` 可跳过）
   - `.ws-change.json`（记录 `created_at` 与 `base_truth_files` 作为基线）
+  - `analysis/` / `patches/` / `review/` / `evidence/`（协同工件目录；默认预创建）
 - 模板来源优先级：
   1) `changes/templates/`
   2) `workflow/changes/templates/`（兼容旧布局）
@@ -252,7 +298,17 @@
   - 若当前分支不是 `change/<change-id>`：默认合并到当前分支。
   - 若当前分支是 `change/<change-id>`：尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch` 作为目标分支；若缺失则要求显式指定 `--into/--base`。
 - 约束：要求工作区 clean（无未提交改动）。
+- 硬门禁：finish 前必须满足完整 review gate：
+  - `changes/<id>/review/spec-review.md`
+  - `changes/<id>/review/quality-review.md`
+  - `.agentdocs/tmp/aiws-validate/*.json`
+  - `changes/<id>/evidence/verify-before-complete.md`
 - worktree 场景：若目标分支正在其它 worktree 被 checkout，会提示到对应 worktree 执行。
+- 生命周期语义：
+  - 本地 merge 成功但 push / cleanup 未完成时，只记为“finish 已开始”，治理阶段仍停留在 `ws-finish`
+  - 若 `--push` 后只完成了 push、但 cleanup 仍未完成，命令应返回非 0，并记录 `finish_cleanup_pending` 以提示修复后重跑
+  - 旧版错误写入的 `finish_done`（例如 `push: false` 或 `cleanup: not_requested`）不得视为真正完成；CLI 应降级为未完成状态，允许重试
+  - 只有完整 finish 成功（兼容旧事件 `finish`，新事件 `finish_done`）后，治理阶段才可进入 `ws-handoff`
 
 接口（仅定义）：
 - `aiws change finish [<change-id>] [--into <branch> | --base <branch>]`
@@ -275,13 +331,14 @@
 - `--strict`：强门禁（例如 WS:TODO、占位符、缺归因、truth drift 等都失败）。
 - `--allow-truth-drift`：仅用于紧急场景跳过 truth drift gating（仍会输出 warnings；不建议常用）。
 - `--check-evidence`：证据存在性门禁（可选）：校验 `Evidence_Path` 声明的路径必须是工作区相对路径且文件存在；并要求至少包含 1 条持久证据路径（`changes/<id>/evidence/...` 或 `changes/<id>/review/...`）。
-- `--check-scope`：scope 门禁（可选，best-effort）：要求 proposal/plan 中包含 “In Scope” 与 “Out of Scope” 标记（用于减少 scope creep）。
+- 当启用 `--check-evidence` 时，还必须检查 finish gate：`spec_review` / `quality_review` / `validate_stamp` / `verify_before_complete`。
+- `--check-scope`：scope 门禁（可选）：读取 `proposal.md -> Plan_File` 指向计划中的 `## Scope` / `## 影响范围（Scope）`，优先消费 `### In Scope` 下的文件/目录模式（支持 glob）；超出范围的文件在 `--strict` 下失败、否则警告。
 
 接口（仅定义）：
 - `aiws change validate [<change-id>] [--strict] [--allow-truth-drift] [--check-evidence] [--check-scope]`
 
 说明：
-- `--check-evidence/--check-scope` 默认不启用，避免对历史 change 造成行为破坏；交付阶段建议启用 `--check-evidence`。
+- `--check-evidence/--check-scope` 默认不启用，避免对历史 change 造成行为破坏；交付阶段建议启用 `--check-evidence`，开发/交付前建议显式补跑一次 `--check-scope`。
 
 ### `aiws change evidence`
 
@@ -292,6 +349,12 @@
     - `changes/<change-id>/proposal.md` 的 `Evidence_Path`
     - `Plan_File` 指向的计划文件中的 `Evidence_Path`（若存在）
   - 若存在 `.agentdocs/tmp/review/codex-review.md` 且 `changes/<id>/review/codex-review.md` 不存在：复制为持久 review 证据。
+- 协同收敛：
+  - 若 `analysis/` / `patches/` / `review/` / `evidence/` 目录缺失，会在执行时自动补齐。
+  - 若仅存在 `.agentdocs/tmp/review/codex-review.md` 且 `changes/<id>/review/codex-review.md` 不存在，可先作为有效 review 信号参与阶段推断；执行 evidence 时应复制为持久 review 证据。
+  - 若存在 `.agentdocs/tmp/review/spec-review.md`、`.agentdocs/tmp/review/quality-review.md`、`.agentdocs/tmp/review/verify-before-complete.md` 且对应持久路径不存在，执行 evidence 时应同步收敛为持久 gate 证据。
+  - 收集 `review/` 下全部 `.md` 文件（支持多 reviewer），并生成 `changes/<id>/evidence/collaboration-summary-<timestamp>.json`。
+  - 生成 `changes/<id>/evidence/delivery-summary-<timestamp>.md`，概述协同工件数量、绑定信息、质量门结果与下一步建议。
 
 接口（仅定义）：
 - `aiws change evidence [<change-id>] [--no-validate] [--allow-fail]`
@@ -310,6 +373,11 @@
   - `archived_to`
   - `archived_truth_files`
 - 写入 stamp（不含 secrets）：`.agentdocs/tmp/change-archive/<timestamp>-<change-id>.json`
+- 生成 `changes/archive/<YYYY-MM-DD>-<id>/handoff.md`，其中应包含：
+  - `本次完成`
+  - `关键决策`
+  - `协同记录`（analysis / patches / review / evidence 摘要）
+  - `下一步建议`
 
 接口（仅定义）：
 - `aiws change archive [<change-id>] [--date YYYY-MM-DD] [--force]`
@@ -318,6 +386,20 @@
 
 语义：
 - 信息性命令：列出当前 changes 进度与下一步建议（不修改任何文件）。
+- `status`：
+  - 输出阶段、blockers、evidence 统计与 collaboration 统计。
+  - collaboration 统计至少包含 `analysis` / `patches` / `review` / `evidence_dir`。
+  - 若 review 仅来自 tmp fallback，应额外输出有效 review signal（如 `review_signal: effective=1 source=tmp_fallback`）。
+  - 应显式输出 review gate 状态，至少覆盖：`spec_review` / `quality_review` / `validate_stamp` / `verify_before_complete`。
+  - 若 change worktree metadata 已 stale，应输出 warning 并提示 `git worktree prune`。
+- `next`：
+  - 基于 blockers / 未完成任务 / collaboration 工件给出下一步建议。
+  - 若存在委托 patch 草案，应提示“先人工审查，不要视为已自动应用”。
+  - 若存在委托分析但尚未形成 review 汇总，应提示先收敛再交付。
+  - 若 dual review 未完成，应显式引导到 `ws-spec-review` / `ws-quality-review`。
+  - 若交付证据已存在但 finish gate 未齐，应显式引导到 `aiws validate . --stamp` / `ws-verify-before-complete`。
+  - 若 `finish_local` / `finish_failed` / `finish_cleanup_pending` 已出现，不应直接建议 handoff；应提示先补完 finish。
+- `list`：按 change 汇总显示阶段与协同/证据概况；供 dashboard/API 复用同一状态模型。
 
 接口（仅定义）：
 - `aiws change list`

package/docs/collaboration-artifacts.md

@@ -0,0 +1,62 @@
+# collaboration-artifacts
+
+## 目的
+
+这份文档定义 `aiws` 在 change 生命周期中的协同工件约定，让“委托分析 / patch 草案 / 多 reviewer 审查 / 交接”都有稳定落盘路径，而不是只存在于会话里。
+
+## 标准目录
+
+每个 active change 建议使用以下目录：
+
+```text
+changes/<change-id>/
+  analysis/
+  patches/
+  review/
+  evidence/
+```
+
+含义：
+- `analysis/`：外部或子 agent 的分析报告、调研结论、备选方案。默认视为只读输入。
+- `patches/`：外部或子 agent 生成的 patch / diff 草案。默认视为未应用草案。
+- `review/`：多 reviewer 的审查结果。允许并行存在多个文件。
+- `evidence/`：交付前收敛出的持久证据，例如 validate summary、delivery summary、collaboration summary。
+
+## 规则
+
+- 外部分析不等于实现完成。主 agent 必须把采用与否的结论写入 `review/` 或最终 handoff。
+- patch 草案不自动应用。主 agent 或人工必须先审查，再决定是否将其转换成真实代码改动。
+- `review/` 允许多人并行，例如：
+  - `codex-review.md`
+  - `spec-review.md`
+  - `quality-review.md`
+  - `reviewer-a.md`
+  - `security-review.md`
+- 若启用了 dual review / finish gate，优先使用固定文件名：
+  - `changes/<change-id>/review/spec-review.md`
+  - `changes/<change-id>/review/quality-review.md`
+  - `changes/<change-id>/evidence/verify-before-complete.md`
+- `aiws change evidence <change-id>` 应把 review / validate / collaboration summary 收敛到 `evidence/`，并在目标文件缺失时收敛以下 tmp fallback：
+  - `.agentdocs/tmp/review/codex-review.md`
+  - `.agentdocs/tmp/review/spec-review.md`
+  - `.agentdocs/tmp/review/quality-review.md`
+  - `.agentdocs/tmp/review/verify-before-complete.md`
+- `aiws change archive <change-id>` 生成的 `handoff.md` 应概述协同工件，帮助下一次会话快速接手。
+
+## 生命周期映射
+
+| 阶段 | 协同工件 |
+| --- | --- |
+| `ws-dev` | 生成或更新 `analysis/`、`patches/` |
+| `ws-review` | 审查委托结果，并把最终结论写入 `review/` |
+| `aiws change evidence` | 收敛 review / validate / collaboration summary 到 `evidence/` |
+| `ws-handoff` / archive | 在 `handoff.md` 中概述协同工件与最终结论 |
+
+## 判断标准
+
+只有在满足以下条件时，协同才算真正进入 `aiws` workflow：
+
+- 有稳定目录承载，而不是散落在聊天记录或临时文件里。
+- patch 草案和最终代码改动被清楚区分。
+- 多 review 可以并行存在，并能在交付前被收敛。
+- handoff 能让下一位协作者知道“看哪些文件、哪些结论已经确认、哪些仍待处理”。

package/docs/opencode-omo-adapter.md

@@ -0,0 +1,135 @@
+# OpenCode + oMo Adapter
+
+目标：当项目在 OpenCode 中启用了 `oh-my-opencode`（oMo）时，`aiws` 不替换它，而是在 `ws-*` skill 里优先借用 oMo 的现有 agent。
+
+边界：
+- `aiws` 继续负责 workflow contract、artifact convention、review gate 与 fallback discipline。
+- oMo 继续负责 OpenCode 里的 agent harness、hooks、session 管理与运行时编排。
+- 不新增第二套 orchestrator；也不复制一套与 oMo 冲突的 agent 体系。
+
+## 检测约定
+
+以下任一条件成立时，可认为当前项目“优先按 oMo 方式适配”：
+
+- 项目根存在 `.opencode/oh-my-opencode.json`
+- 用户明确说明已安装并启用了 oMo
+- 当前 OpenCode 会话可用 agent 中出现 `planner-sisyphus`、`librarian`、`explore`、`oracle`
+
+若无法确认：
+- 不要假设 oMo 一定可用
+- 进入 fallback：普通 OpenCode agent / 单 agent + AIWS 协同工件模式
+
+CLI 辅助探测：
+- 可在项目根运行 `aiws opencode status .`
+- 该命令只做探测与提示，不接管 OpenCode / oMo 的运行时编排
+
+## 推荐项目级配置
+
+若你希望按项目把 oMo agent 集合与 AIWS workflow 对齐，建议只做最小 `agents` override，不接管 hooks / MCP / LSP。
+
+模板建议文件：
+- `packages/spec/templates/workspace/.opencode/oh-my-opencode.json.example`
+
+建议内容：
+
+```json
+{
+  "agents": {
+    "planner-sisyphus": {
+      "enabled": true,
+      "replace_plan": false
+    },
+    "librarian": {
+      "enabled": true
+    },
+    "explore": {
+      "enabled": true
+    },
+    "oracle": {
+      "enabled": true
+    }
+  }
+}
+```
+
+说明：
+- `replace_plan=false` 是保守默认，避免项目级配置直接替换掉 OpenCode 默认 `plan` 行为。
+- 这份示例的目的只是让 `ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 有稳定的优先 agent 可用。
+- 若你已经在用户级配置里启用了这些 agent，项目级配置可以不写。
+
+## 角色映射
+
+`aiws` 的治理角色与 oMo agent 的推荐映射如下：
+
+| AIWS Role | 优先 oMo Agent | 用途 | 回退 |
+| --- | --- | --- | --- |
+| `planner` | `planner-sisyphus` | 计划、拆解、执行路径设计 | OpenCode `plan` / 当前 agent 本地规划 |
+| `explorer` | `explore` | 代码导航、依赖关系、模式发现 | 当前 agent 只读探索 |
+| `explorer` | `librarian` | 文档、规范、代码知识检索 | 当前 agent 只读探索 |
+| `reviewer` | `oracle` | 独立审查、解释、问答式风险验证 | 当前 agent 本地 review |
+| `integrator` | 当前主 agent | 汇总结论、落盘、最终验证、进入下一阶段 | 无；始终由主 agent 收敛 |
+
+说明：
+- `planner-sisyphus` 是 oMo 的默认 agent；官方文档说明它与 OpenCode 的 `plan` agent 是同一能力，只是因为 SDK 限制做了重命名。
+- `librarian` 和 `explore` 都偏探索，但前者更偏文档/知识管理，后者更偏代码导航与结构理解。
+- `oracle` 适合做 questions / explanations / independent review，不应直接承担大范围写盘实现。
+
+## 各 skill 的优先委托策略
+
+### `ws-plan`
+
+- 若检测到 oMo：
+  - 优先用 `planner-sisyphus` 生成计划框架
+  - 需要仓库结构探索时，再委托 `@explore`
+  - 需要文档/规范/依赖查证时，再委托 `@librarian`
+- 主 agent 负责把结果收敛为 `plan/...` 与 `changes/<id>/proposal.md`
+
+### `ws-review`
+
+- 若检测到 oMo：
+  - 优先让 `@oracle` 做独立审查
+  - 必要时用 `@explore` 补 diff 影响面
+  - 必要时用 `@librarian` 补 requirements / docs / 依赖上下文
+- 主 agent 负责把 findings 收敛到 `changes/<id>/review/...`
+
+### `ws-spec-review`
+
+- 若检测到 oMo：
+  - 优先让 `@oracle` 审 requirements / plan / gate / evidence 完整性
+  - 必要时让 `@librarian` 读取规范与文档真值
+- 主 agent 负责输出 blocker / warning / next
+
+### `ws-quality-review`
+
+- 若检测到 oMo：
+  - 优先让 `@oracle` 审行为正确性、回归与测试缺口
+  - 必要时让 `@explore` 做代码路径补充探索
+- 主 agent 负责输出 findings / gaps / next
+
+### `ws-delegate`
+
+- `ws-delegate` 自己不编排 runtime
+- 它只负责声明：
+  - 该委托应该优先调用哪个 oMo agent
+  - `readScope` / `writeScope`
+  - `artifactTargets`
+  - fallback
+
+## 执行规则
+
+- skill 里写的是“优先委托策略”，不是保证当前会话一定能直接切换到某个 agent。
+- 若当前 OpenCode 会话无法直接切换到某个 primary agent：
+  - 不要卡住
+  - 回退为当前 agent + `@subagent` 可用的能力
+  - 再不行就回退为单 agent 执行
+- 任何 oMo agent 的输出都必须回收到 AIWS 约定路径：
+  - `changes/<id>/analysis/`
+  - `changes/<id>/patches/`
+  - `changes/<id>/review/`
+  - `changes/<id>/evidence/`
+
+## 非目标
+
+- 不由 `aiws` 接管 `.opencode/oh-my-opencode.json` 的完整配置。
+- 不由 `aiws` 覆盖 oMo 的 hooks、session recovery、compaction 或 agent harness。
+- 不要求 skill 一定“自动调起” oMo 的全部 agent；只要求写清优先顺序与回退策略。