@aipper/aiws-spec 0.0.27 → 0.0.29

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

@@ -1,91 +1,107 @@
 ---
 name: using-aiws
-description: 默认 workflow bootstrap/router：先读真值，再路由到正确的 ws-* 入口
+description: 使用时机：新会话开始、不确定下一步做什么时。触发词：路由、bootstrap、Router、工作流入口、下一步做什么。注意：已明确阶段可直接进入对应 ws-*。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：
-- 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
-- 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
-- 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+目标：默认入口，先读真值文件，判定当前任务 workflow，再进入具体 `ws-*` skill。若意图不明确：先澄清，不直接进入实现。
 
-阶段定位：
-- bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
+阶段定位：bootstrap/router 阶段；负责分流，不直接完成实现。
+
+## 必需输入
 
-必需输入：
 - 当前任务描述
-- `AI_PROJECT.md`
-- `REQUIREMENTS.md`
-- `AI_WORKSPACE.md`
-- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
-
-必需输出：
-- `Root:` 当前项目根
-- `Found:` 实际读取到的真值文件
-- `OpenCode mode:` `oMo-enabled` / `standard-opencode`
-- `Task intent:` 当前任务意图分类
-- `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
-- `Route:` 选中的下一步 skill
-- `Why:` 选择该 route 的原因
-- `Next:` 进入对应 skill，或先提澄清问题
-
-阻断条件：
+- `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 若已存在：`change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+
+## 必需输出
+
+- `Root:` / `Found:` / `OpenCode mode:` / `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`
+
+## 阻断条件
+
 - 无法确定项目根目录
 - 缺失任一真值文件
 - 无法明确当前任务意图
 - 无法明确归因或验证入口，且不能安全推断
 
-完成判定：
-- 已经明确给出单一路由结果，并进入对应 `ws-*` skill；或已提出关键澄清问题并停止。
-
-执行步骤（强制）：
-1) 先遵守 `$ws-preflight` 的真值读取要求：
-   - 定位项目根目录
-   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
-   - 若检测到 `.opencode/oh-my-opencode.json`：输出 `OpenCode mode: oMo-enabled`，并注明后续会优先借用 `planner-sisyphus` / `explore` / `librarian` / `oracle`
-   - 若未检测到：输出 `OpenCode mode: standard-opencode`
-   - 输出 `Root:` / `Found:` / `Missing:`
-2) 若缺失任一真值文件：
-   - 不进入实现
-   - 输出下一步：先 `aiws init .`（或 `npx @aipper/aiws init .`），然后重新执行 `$using-aiws`
-   - 此时 route 视为 `$ws-preflight`
-3) 根据 `packages/spec/docs/workflow-router-rules.json` 判定任务属于哪一类：
-   - 需求/验收/合同变更：`$ws-req-review`
-   - 评审/审计/找风险：`$ws-review`
-   - finish / merge / push / cleanup：`$ws-finish`
-   - handoff / archive summary：`$ws-handoff`
-   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
-   - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
-4) 若任务意图或归因不明确：
-   - 只问 1-3 个关键澄清问题
-   - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
-   - 然后停止；不要直接写代码
-5) 若已确定 route：
-   - 先输出：
-     - `Task intent:`
-     - `Binding:`
-     - `Route:`
-     - `Why:`
-   - 若 `Route: $ws-dev` 且任务属于 simple/local 单点修复：
-     - `Next:` 可优先进入 `$ws-dev-lite`
-   - 否则：
-     - `Next:` 进入对应主 skill
-   - 然后在同一轮中继续遵循对应 skill 的契约
-6) 路由约束：
-   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
-   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
-   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
-7) 若执行过程中发现复杂度升高：
-   - 从 `$ws-dev` 回退到 `$ws-plan`
-   - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
-
-输出模板：
-- `Root:` <path>
-- `Found:` <files>
-- `OpenCode mode:` <oMo-enabled / standard-opencode>
-- `Task intent:` <分类>
-- `Binding:` <清晰 / 缺失项>
-- `Route:` <$ws-... 或 clarify>
-- `Why:` <一句到三句>
-- `Next:` <继续执行对应 skill，或提出澄清问题>
+## 执行步骤
+
+### 1. Preflight
+
+读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+
+- 若检测到 `.opencode/oh-my-opencode.json`：输出 `oMo-enabled`
+- 若未检测到：输出 `standard-opencode`
+- 若缺失任一真值文件 → route = `$ws-preflight`，建议先 `aiws init .`
+
+### 2. 路由判定
+
+根据 `packages/spec/docs/workflow-router-rules.json` 判定：
+
+| 意图 | Route |
+|------|-------|
+| 需求/验收/合同变更 | `$ws-req-review` |
+| 评审/审计/找风险 | `$ws-review` |
+| finish/merge/push/cleanup | `$ws-finish` |
+| handoff/archive | `$ws-handoff` |
+| 先出设计方案 | `$ws-design` |
+| 更新规范/验收标准 | `$ws-spec-update` |
+| 中大型实现 | `$ws-plan` |
+| 小步明确实现/修复 | `$ws-dev` |
+| 极简修复 | `$ws-dev-lite` |
+
+注：`$ws-dev` 默认走 subagent-first 策略（详见 `packages/spec/docs/opencode-subagent-first.md`）。主 session 应优先通过 `$ws-delegate` 派发 `aiws-worker`，除非用户明确说"直接改"或"do it inline"。
+
+### 3. 意图不明确
+
+只问 1-3 个关键问题，明确缺什么（意图、Req_ID/Problem_ID、verify、change 上下文），然后停止。
+
+### 4. Continuation Routing（新 session 恢复）
+
+`.opencode/plugins/aiws-session-start.js` 自动注入 `<resume-recommendation>` 块，包含 active change ID、phase、journal 摘要及 next action。
+
+续跑决策表（与 `aiws-context.js#getChangeState` 同步）：
+
+```
+┌──────────────────┬──────────────────────────────────────────────┐
+│ Phase            │ 推荐 Next Action                             │
+├──────────────────┼──────────────────────────────────────────────┤
+│ none（无 change） │ ws-intake 或 ws-plan 建立 change 上下文       │
+│ intake           │ ws-intake 继续澄清，或 ws-plan 转到规划        │
+│ planning         │ plan 存在 → ws-plan-verify；否则 ws-plan       │
+│ ready-for-dev    │ 派发 aiws-worker（subagent-first）             │
+│ in-progress      │ patches 存在 → aiws-reviewer + ws-review      │
+│                  │ 上次 DONE_WITH_CONCERNS → ws-quality-review   │
+│                  │ 否则 worker 继续或 aiws-reviewer 审查          │
+│ review           │ evidence 齐 → ws-finish/ws-commit              │
+│                  │ 否则补 evidence 再提交                         │
+│ finished         │ ws-finish 收尾归档                             │
+│ unknown          │ ws-preflight 重新评估                          │
+└──────────────────┴──────────────────────────────────────────────┘
+```
+
+特殊状态：
+- 上次 delegation 返回 `BLOCKED` → 先解决 blocker 再继续
+- 上次 delegation 返回 `NEEDS_CONTEXT` → 补 context JSONL 后重新派发
+- Subagent-first 默认：`ready-for-dev` / `in-progress` 默认派发 worker/reviewer
+
+### 5. 输出路由
+
+```
+Root: <path>
+Found: <files>
+OpenCode mode: <oMo-enabled / standard-opencode>
+Task intent: <分类>
+Binding: <清晰 / 缺失项>
+Route: <$ws-... 或 clarify>
+Why: <一句到三句>
+Next: <继续执行对应 skill，或提出澄清问题>
+```
+
+## 约束
+
+- Router 自己不实现代码；不给 route 前不直接改代码
+- 一次只选一个主 route
+- 若复杂度升高：`$ws-dev` 回退到 `$ws-plan`；`$ws-finish` 回退到前置门禁

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

@@ -1,6 +1,6 @@
 ---
 name: ws-analyze
-description: 分析（定位问题与收集上下文）
+description: 使用时机：需要分析问题、定位根因、收集上下文时。触发词：分析、定位、调查、诊断。注意：直接改代码请用 ws-dev。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -0,0 +1,46 @@
+---
+name: ws-auto
+description: 使用时机：OpenCode/oMo 会话启动、自动 bootstrap 时。触发词：启动、bootstrap、自动、watchdog。注意：首次初始化请用 ws-preflight。
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 为当前 OpenCode 工作区执行一次显式 auto bootstrap，而不是把逻辑塞进用户自己的 `opencode` wrapper。
+- 先检查真值文件、托管内容与 autonomy 相关文件是否需要更新。
+- 若当前仓库已启用 oMo 且 watchdog 条件齐备：自动确保 tmux 中已有 watchdog。
+- 最后给出明确的下一步路由，而不是停留在状态描述。
+
+必需输入：
+- `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前项目根目录
+- 当前任务意图（若已知）
+
+必需输出：
+- `Auto Bootstrap:`
+- `Update:`
+- `OpenCode mode:`
+- `Watchdog:`
+- `Next:`
+
+阻断条件：
+- 缺失任一真值文件
+- 当前目录不是 AIWS 工作区，且不存在 `.aiws/manifest.json`
+- `.opencode/oh-my-opencode.json` 是无效 JSON
+
+执行步骤（强制）：
+1) 先运行 `/ws-preflight`，确认真值文件与项目根路径。
+2) 在项目根运行：`aiws opencode auto .`
+3) 根据输出收敛结果：
+   - 若输出 `update: required` 且随后已执行 `aiws update .`：在 `Update:` 中写明 `applied`
+   - 若输出 `mode: oMo-enabled`：在 `OpenCode mode:` 中写明 `oMo-enabled`
+   - 若输出 `watchdog:` 为 `already-running` / `created` / `started-with-new-session`：在 `Watchdog:` 中写明已就绪
+   - 若输出 `watchdog: skipped (...)`：把跳过原因原样收敛到 `Watchdog:`
+4) 给出单一 `Next:`：
+   - 若 watchdog 已就绪且任务意图明确：进入 `/using-aiws`、`/ws-plan`、`/ws-dev` 或 `/ws-review`
+   - 若只想先声明 autonomous 合同：进入 `/ws-autonomy`
+   - 若因缺配置/缺 tmux/invalid JSON 被跳过：先修复对应缺口，不直接假装已进入 autonomous 模式
+
+安全：
+- `ws-auto` 允许调用 `aiws update .` 来刷新 AIWS 托管内容，但不自动启用 `.opencode/oh-my-opencode.json`。
+- `ws-auto` 只会确保 watchdog 启动；不会自动批准 host permission，也不会自动执行 tmux rescue。

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

@@ -0,0 +1,62 @@
+---
+name: ws-autonomy
+description: 使用时机：需要自主协作、无人值守执行时。触发词：自主、自动化、协作、retry、rescue。注意：实验功能，不用于正式交付。
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 为当前 OpenCode 任务声明 autonomous execution mode，而不是直接接管 runtime。
+- 明确 completion contract / retry contract / rescue policy / evidence path。
+- 在需要时引导使用 `.opencode/helpers/tmux-swarm-scan.sh` 与 `tmux-swarm-rescue.sh`。
+- 在需要时引导使用 `.opencode/helpers/approval-whitelist-check.sh` 判定低风险命令/路径是否可自动放行。
+- 在需要时引导使用 `.opencode/helpers/approval-whitelist-run.sh` 执行已获 `allow` 的简单命令。
+- 在需要时引导使用 `.opencode/helpers/approval-whitelist-watchdog.sh` 轮询待执行队列。
+
+必需输入：
+- `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- `packages/spec/docs/opencode-autonomous-swarm.md`
+- `packages/spec/docs/opencode-omo-adapter.md`
+- 当前任务绑定（`Req_ID` / `Problem_ID` / `change` / `Verify`）
+
+必需输出：
+- `Execution Mode:` `single-agent` / `omo-native` / `omo-native + tmux-swarm`
+- `Completion Contract:`
+- `Retry Contract:`
+- `Rescue Policy:`
+- `Evidence:`
+- `Next:`
+
+阻断条件：
+- 当前任务未绑定
+- 无法确认当前是否启用了 oMo，又不能接受回退
+- 需要 tmux swarm 但当前环境没有 `tmux`
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`，确认真值文件完整。
+2) 判断当前模式：
+   - 若未启用 `.opencode/oh-my-opencode.json`：`single-agent`
+   - 若启用了 oMo：`omo-native`
+   - 若启用了 oMo 且当前接受 tmux 巡检/救援：`omo-native + tmux-swarm`
+3) 输出 `Completion Contract:`，至少包含：
+   - 真值文件已读取
+   - 任务/change 已绑定
+   - Verify 已执行
+   - review/evidence 已落盘
+4) 输出 `Retry Contract:`：
+   - `ws-plan-verify` 失败 -> `ws-plan`
+   - `ws-review` blocker -> `ws-dev`
+   - `validate` 失败 -> `ws-dev`
+5) 输出 `Rescue Policy:`：
+   - 只允许 `(y/n)`、`Press Enter to continue`、退出 copy-mode
+   - 不允许 blind `Ctrl+C` / 广播 shell 命令 / 自动 commit/push
+6) 若选择 `omo-native + tmux-swarm`：
+   - 如需判定某个低风险命令是否可自动放行：运行 `bash .opencode/helpers/approval-whitelist-check.sh . --kind <read|write|host-permission> --command "<cmd>" [--path "<target>"]`
+   - 如需让 watchdog 真正执行已放行的简单命令：运行 `bash .opencode/helpers/approval-whitelist-run.sh . --kind <read|write|host-permission> --command "<cmd>" [--path "<target>"]`
+   - 如需持续轮询外部蜂群写入的待执行项：运行 `bash .opencode/helpers/approval-whitelist-watchdog.sh . --once` 或去掉 `--once` 持续运行
+   - 提示先运行 `.opencode/helpers/tmux-swarm-scan.sh`
+   - 如需安全救援，再运行 `.opencode/helpers/tmux-swarm-rescue.sh`
+
+安全：
+- `ws-autonomy` 不是 runtime controller。
+- 任何 tmux helper 的结果都必须回收到 `.agentdocs/tmp/opencode-autonomy/`，最终再由主 agent 收敛到 `changes/<id>/...`。

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

@@ -1,6 +1,6 @@
 ---
 name: ws-bugfix
-description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片证据，汇总到 issues/fix_bus_issues.csv，并绑定到 changes/<change-id>/）
+description: 使用时机：从禅道/外部系统拉取 bug 进行修复时。触发词：bug、缺陷、修复、禅道、zentao。注意：非禅道小修复请用 ws-dev-lite。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -1,130 +1,18 @@
 ---
 name: ws-commit
-description: 提交（当前分支可直提；submodule 感知；先审计/门禁再 commit）
+description: Thin wrapper for `aiws ws-commit`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-commit
 
-目标：
-- 支持在**当前分支直接提交**（不要求必须先切 `change/<change-id>`）
-- 提交前审计与证据落盘（`$ws-review`）
-- 提交前门禁校验与证据落盘（`aiws validate . --stamp`）
-- 最后执行 `git commit`（commit 前必须让用户确认 message；不使用 `--no-verify` 绕过 hooks）
-- 若仓库含 submodule：提交前识别并提示正确顺序（先 submodule，再 superproject）
- - 若你经常遇到 submodule detached：建议日常拉取使用 `$ws-pull`（尽量把 submodule “挂回分支”且不改变 gitlink commit）
+Thin skill wrapper. Delegates to `aiws ws-commit`. See `aiws ws-commit --help` for details.
 
-安全约束（强制）：
-- 不自动 `git add -A`（避免误提交）；只在用户明确指示时才执行 staging 命令
-- 不自动 push
-- 不写入任何 secrets
-- 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
-- commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
-- 若启用了 `.githooks/commit-msg`：默认按仓库角色区分
-  - superproject / root 仓库（存在 `.gitmodules`）默认允许自由 commit message
-  - submodule / 普通仓库默认提示优先中文
-  - 只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
-
-阶段定位：
-- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
-
-必需输入：
-- 当前分支与 staged diff
-- `$ws-review` 生成的审计证据
-- `aiws validate . --stamp` 生成的校验证据
-- 用户确认后的 commit message
-
-必需输出：
-- `证据（Evidence）:` review 文件路径 + validate stamp 路径
-- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
-- `提交信息（Commit）:` 最终提交信息
-
-阻断条件：
-- 没有 staged changes
-- submodule 工作区不干净或 detached 处理不完整
-- 用户未确认 commit message
-- validate 失败
-
-完成判定：
-- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
-
-执行步骤（建议）：
-1) 运行 `$ws-preflight`（确保真值文件就绪）。
-2) 运行 `$ws-review`（优先生成审计证据：`changes/<change-id>/review/codex-review.md`；无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`）。
-3) 运行门禁校验并写 stamp：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate . --stamp
+  ./node_modules/.bin/aiws ws-commit
 elif command -v aiws >/dev/null 2>&1; then
-  aiws validate . --stamp
+  aiws ws-commit
 else
-  npx @aipper/aiws validate . --stamp
-fi
-```
-4) 输出当前提交上下文（必须输出给用户确认）：
-```bash
-git branch --show-current
-git status --porcelain
-```
-5) 检测是否存在 submodule（有则进入 submodule 感知模式）：
-```bash
-if [[ -f .gitmodules ]]; then
-  git config --file .gitmodules --get-regexp '^submodule\..*\.path$' || true
-else
-  echo "[info] no .gitmodules"
-fi
-```
-6) 若存在 submodule，逐个检查子仓库工作区是否干净：
-```bash
-while read -r _ sub_path; do
-  [[ -z "${sub_path:-}" ]] && continue
-  echo "== submodule: ${sub_path} =="
-  git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
-  git -C "${sub_path}" status --porcelain || true
-done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true)
-```
-判定规则（强制）：
-- 任一 submodule `git status --porcelain` 非空：停止 superproject commit，先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
-- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target_branch>`；不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
-处理指引（detached submodule）：
-```bash
-cur_branch="$(git branch --show-current)"
-change_id="$(echo "${cur_branch}" | sed -n 's|^change/||p')"
-targets="changes/${change_id}/submodules.targets"
-
-source tools/ws_resolve_sub_target.sh
-ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${cur_branch}" || exit 2
-target_branch="${_resolved_branch}"
-remote="${_resolved_remote}"
-
-git -C "${sub_path}" fetch "${remote}" --prune
-if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
-  echo "error: missing ${remote}/${target_branch} for submodule path=${sub_path}"
-  exit 2
+  npx @aipper/aiws ws-commit
 fi
-git -C "${sub_path}" checkout -B "aiws/pin/${target_branch}" HEAD
-git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
 ```
-7) 检查当前 staging 内容（必须输出给用户确认）：
-```bash
-git status --porcelain
-git diff --staged --submodule=short
-```
-8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-9) 生成中文 commit message 草案（格式：`<类型>: <简述>`），输出给用户确认后再执行。
-   - 类型参考：`功能` / `修复` / `重构` / `文档` / `测试` / `构建` / `杂项`
-   - 简述用一句话概括本次改动的"为什么"而非"改了什么"
-   - 命令/路径/代码标识符保持原样不翻译
-   - 若用户给出全英文 message：优先改写成中文；若用户明确要求保留英文，也可以提交（但 strict 模式下会被 hook 拒绝）
-10) 执行提交（不带 `--no-verify`）：
-```bash
-git commit -m "<message>"
-```
-11) 输出提交结果（可选）：
-```bash
-git show --stat --oneline -1
-```
-
-输出要求：
-- `证据（Evidence）:` `changes/<change-id>/review/codex-review.md`（无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`） + `.agentdocs/tmp/aiws-validate/*.json`
-- `上下文（Context）:` 当前分支 + 是否检测到 submodule + 若阻断则给出阻断原因
-- `提交信息（Commit）:` 最终使用的 commit message（仅当用户确认后）

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

@@ -1,63 +1,116 @@
 ---
 name: ws-delegate
-description: 原生多 agent 委托入口（OpenCode + oMo 优先；先写委托合同，再调用对应 agent）
+description: 使用时机：需要拆分子任务、委托给子 agent 时。触发词：委托、子 agent、拆分、并行、sub-agent。注意：简单任务不需委托。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在 OpenCode 中，优先借用 `oh-my-opencode` 的现有 agent 做任务拆分；若 oMo 不可用，再回退为普通 OpenCode delegation / 单 agent 执行。
 
-必需输入：
+## 必需输入
+
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
 - delegation contract：`packages/spec/docs/workflow-delegation-contracts.md`
+- 上下文策展规范：`packages/spec/docs/workflow-delegation-context-injection.md`
 - OpenCode + oMo 适配说明：`packages/spec/docs/opencode-omo-adapter.md`
+- 连续执行循环：`packages/spec/docs/opencode-subagent-first.md`
 - 当前任务已绑定 `Req_ID` / change / Verify
 
-必需输出：
-- `Delegation Plan:` 写清 role / preferred agent / readScope / writeScope / artifactTargets / fallback
+## 必需输出
+
+- `Delegation Plan:` role / preferred agent / readScope / writeScope / artifactTargets / fallback
+- `Context Curation:` 上下文策展详情
 - `Execution Mode:` `omo-native` / `opencode-native` / `single-agent`
 - `Evidence:` 产物路径
 - `Next:` 回到 `ws-dev` / `ws-review` / `ws-commit` / `ws-finish`
 
-阻断条件：
+## 阻断条件
+
 - 任务未绑定
 - 没有写清委托边界
+- 上下文策展未执行（未生成 JSONL 或未在 prompt 中引用）
 - 无法判断当前是否可用 oMo，又不能接受回退
 
-推荐映射：
-- `planner` -> `planner-sisyphus`
-- `explorer` -> `@explore` / `@librarian`
-- `reviewer` -> `@oracle`
-- `integrator` -> 当前主 agent
-
-执行步骤（建议）：
-1) 先读真值文件、delegation contract 和 `opencode-omo-adapter.md`。
-2) 判断当前项目是否启用了 oMo：
-   - 优先检查 `.opencode/oh-my-opencode.json`
-   - 或当前会话是否明确可用 `planner-sisyphus` / `librarian` / `explore` / `oracle`
-3) 先写 `Delegation Plan:`：
-   - `role`
-   - `preferred agent`
-   - `task`
-   - `readScope`
-   - `writeScope`
-   - `artifactTargets`
-   - `fallback`
-4) 若 oMo 可用：
-   - planning 优先 `planner-sisyphus`
-   - 文档/知识检索优先 `@librarian`
-   - 代码导航与结构探索优先 `@explore`
-   - 独立审查优先 `@oracle`
-5) 主 agent 统一收敛结果，并把产物回收到：
-   - `changes/<id>/analysis/`
-   - `changes/<id>/patches/`
-   - `changes/<id>/review/`
-   - `changes/<id>/evidence/`
-6) 若 oMo 不可用：
-   - 输出 `Execution Mode: opencode-native` 或 `Execution Mode: single-agent`
-   - 不阻断工作流，继续按 AIWS 委托合同执行
+## 角色映射
+
+| aiws 角色 | oMo Agent |
+|-----------|-----------|
+| `planner` | `planner-sisyphus` |
+| `explorer` | `@explore` / `@librarian` |
+| `reviewer` | `@oracle` |
+| `integrator` | 当前主 agent |
+
+## 连续执行循环（Worker → Reviewer → Fix）
+
+默认闭环（详见 `packages/spec/docs/opencode-subagent-first.md`）：
+
+1. 主 session 策展上下文 JSONL → dispatch `aiws-worker`
+2. 检查 worker 返回状态（DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED）
+3. DONE → dispatch `aiws-reviewer`
+4. Reviewer pass → 收敛 evidence；fail → 返回 worker 修复（最多 3 次）
+5. DONE_WITH_CONCERNS → 先 `ws-quality-review`
+6. NEEDS_CONTEXT → 补充上下文重试（最多 2 次）
+7. BLOCKED → 输出 blocker 详情，不继续
+
+## 上下文策展
+
+详细规范见 `packages/spec/docs/workflow-delegation-context-injection.md`。
+
+策展步骤：
+1. 读取合同基线（`delegation-contracts.json` 中对应角色的 `contextFiles`）
+2. 展开 glob 为实际路径（替换 `<id>`）
+3. 委托者调整：添加/删除/调整 priority/sections
+4. 预算检查：high+medium ≤ 5 文件，总行数 ≤ 4000
+5. 写入 `changes/<id>/analysis/<role>-context.jsonl`
+
+OpenCode 插件 `aiws-inject-context` 会自动注入 JSONL 上下文——只需在 `task()` 中指定 `role: <role>`。
+
+## 子 agent 返回协议
+
+```
+**Status:** DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+**Completed:** 实现内容
+**Files Changed:** 文件路径
+**Verification:** 命令 + 结果
+**Artifacts:** analysis|patches|review|evidence 下的路径
+**Concerns:** 疑虑或未完成项
+```
+
+### 状态处理
+
+- **DONE**: 进入 ws-review；若已过 review 则准备 ws-finish
+- **DONE_WITH_CONCERNS**: 先 ws-quality-review，根据风险决定是否阻断
+- **NEEDS_CONTEXT**: 补上下文重试（最多 2 次）；仍失败则回退单 agent
+- **BLOCKED**: 停止委托；解 blocker 后重试；永不到达则升级给用户
+
+## Delegation Plan 格式
+
+```
+**Delegation Plan:**
+- role: worker
+- preferred agent: aiws-worker
+- task: <描述>
+- readScope: <文件/目录>
+- writeScope: <文件/目录>
+- artifactTargets: changes/<id>/patches/, changes/<id>/evidence/
+- fallback: single-agent
+Context Curation: changes/<id>/analysis/worker-context.jsonl
+```
+
+## 委托者检查清单
+
+派遣前：
+- [ ] 子 agent prompt 包含上下文引用
+- [ ] JSONL 已写入 `changes/<id>/analysis/<role>-context.jsonl`
+- [ ] 预算检查通过
+- [ ] readScope / writeScope / artifactTargets 已声明
+
+返回后：
+- [ ] 解析 Status 行
+- [ ] 非 DONE → 按状态处理规则行动
+- [ ] 非 DONE → 记录决策到 `delegation-decisions.md`
 
 安全：
-- 不让 `ws-delegate` 变成第二套 orchestrator。
-- 不覆盖 oMo 的 hooks / session / agent harness。
-- 不让 delegated agent 越权写未授权文件。
+- 不让 `ws-delegate` 变成第二套 orchestrator
+- 不让 delegated agent 越权写未授权文件
+- 不跳过 submodule drift check（若 `.gitmodules` 存在）