@aipper/aiws-spec 0.0.28 → 0.0.30

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

@@ -1,63 +1,138 @@
 ---
 name: ws-delegate
-description: 原生多 agent 委托入口（OpenCode + oMo 优先；先写委托合同，再调用对应 agent）
+description: 使用时机：需要拆分子任务、委托给子 agent 时。触发词：委托、子 agent、拆分、并行、sub-agent。注意：简单任务不需委托。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在 OpenCode 中，优先借用 `oh-my-opencode` 的现有 agent 做任务拆分；若 oMo 不可用，再回退为普通 OpenCode delegation / 单 agent 执行。
 
-必需输入：
+## 核心约束
+
+- **Subagent-First**：主 session 只做编排与收敛，不直接写实现代码。所有产出必须由 subagent 完成并可追溯到具体 worker。
+- **Handoff 证据**：每轮委托完成后，worker 必须产出结构化 handoff 到 `changes/<id>/handoff-evidence.md`（完成项、未完成项、残余风险），供主 session 收敛判断。handoff 文件缺失等同于委托未完成。
+
+## 必需输入
+
 - 真值文件：`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`
 
-阻断条件：
+## 执行要求
+
+- 主 session 不直接改代码：所有实现与验证产物必须由 subagent 产出并向 handoff 记录可追溯
+- handoff 证据：手交材料中须含 delegate round number、产出文件路径、已知未关闭项
+
+## 阻断条件
+
 - 任务未绑定
 - 没有写清委托边界
+- 上下文策展未执行（未生成 JSONL 或未在 prompt 中引用）
 - 无法判断当前是否可用 oMo，又不能接受回退
+- handoff 文件 `changes/<id>/handoff-evidence.md` 缺失或为空（委托返回后必须检查）
+
+## 角色映射
+
+| aiws 角色 | oMo Agent |
+|-----------|-----------|
+| `planner` | `planner-sisyphus` |
+| `explorer` | `@explore` / `@librarian` |
+| `reviewer` | `@oracle` |
+| `integrator` | 当前主 agent |
+
+**推荐标准角色**（source: `workflow-delegation-contracts.json` standardRoles）：
+
+| 角色 | 职责 | 读取范围 | 写入范围 |
+|------|------|----------|----------|
+| `implementer` | 代码+测试实现 | 真值文件+change上下文 | 代码文件+测试文件+evidence/ |
+| `reviewer` | 独立审查 | 真值文件+diff+evidence | review/*.md |
+| `researcher` | 分析探索 | 真值文件+外部文档 | analysis/*.md |
+
+这些角色为建议非强制；委托时优先参考但允许根据任务需要调整。
+
+## 连续执行循环（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 已声明
 
-推荐映射：
-- `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 委托合同执行
+返回后：
+- [ ] 解析 Status 行
+- [ ] 非 DONE → 按状态处理规则行动
+- [ ] 非 DONE → 记录决策到 `delegation-decisions.md`
+- [ ] handoff 文件 `changes/<id>/handoff-evidence.md` 已存在且非空
 
 安全：
-- 不让 `ws-delegate` 变成第二套 orchestrator。
-- 不覆盖 oMo 的 hooks / session / agent harness。
-- 不让 delegated agent 越权写未授权文件。
+- 不让 `ws-delegate` 变成第二套 orchestrator
+- 不让 delegated agent 越权写未授权文件
+- 不跳过 submodule drift check（若 `.gitmodules` 存在）

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

@@ -1,230 +1,18 @@
 ---
 name: ws-deliver
-description: 交付（submodules + superproject 分步提交，并安全合并回目标分支）
+description: Thin wrapper for `aiws deliver`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-deliver
 
-目标：
-- 适配 superproject + submodule（数量不固定）的交付收尾：
-  1) 先逐个提交 submodule（每个 repo 单独确认 commit message）
-  2) 再提交 superproject（包含 submodule gitlink 指针更新 + 变更工件/代码）
-  3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`，减少手动 merge 出错）
+Thin skill wrapper. Delegates to `aiws deliver`. See `aiws deliver --help` for details.
 
-非目标（强制）：
-- 不自动 `git add -A`（避免误提交）
-- 不自动 push
-- 不自动删除分支
-
-前置（强制）：
-1) 先运行 `$ws-preflight`。
-2) 确认当前处于 change 分支（推荐）：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）。
-   - 若不在 change 分支：要求用户先切换到 `change/<change-id>`（或在命令里显式提供 `<change-id>`）。
-3) 任何自动提交都必须在提交前输出：
-   - 该 repo 的 `git status --porcelain`
-   - 该 repo 的 `git diff --staged`
-   并让用户确认 commit message（每个 repo 单独确认）。
-
-阶段定位：
-- delivery 阶段；负责在多 repo / submodule 场景下完成顺序提交、证据收敛和最终合并前准备。
-
-必需输入：
-- 当前 `change/<change-id>` 上下文
-- 若存在 submodule：`.gitmodules` + `changes/<change-id>/submodules.targets`
-- 各 repo 当前状态与 staged diff
-
-必需输出：
-- `Submodules:` 每个 submodule 的提交摘要
-- `Superproject:` 主仓库提交摘要
-- `Evidence:` validate stamp 与持久证据路径
-- `Next:` 进入 `$ws-finish` 或 `aiws change finish`
-
-阻断条件：
-- 不在正确的 change 上下文
-- submodule branch / targets 真值不完整
-- 任一 repo 未确认 commit message 或存在未处理冲突
-
-完成判定：
-- submodule 与 superproject 提交都已完成，证据已收敛，且可以安全进入 finish 阶段。
-
-建议流程（按顺序）：
-
-## 0) submodule branch 真值检查（减少 detached 与人为差异）
-如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `$ws-submodule-setup` 并提交 `.gitmodules`，否则后续 `aiws validate .` 会失败，且 `ws-pull/ws-finish` 无法确定性工作。
-> 说明：若同一 superproject 分支内存在多渠道 submodule 目标分支的交付需求，可在 `changes/<change-id>/submodules.targets` 额外声明本次 change 的目标分支；交付时会优先使用该文件（不改变 `.gitmodules` 的团队默认真值）。
-> 生成该文件时，可以按当前状态做默认预填，但必须显式说明来源并让用户确认：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在某个本地分支时默认建议取当前分支；finish/push 最终只认 `submodules.targets`。
 ```bash
-if [[ -f .gitmodules ]]; then
-  missing=0
-  while read -r key sub_path; do
-    name="${key#submodule.}"; name="${name%.path}"
-    b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-    if [[ -z "${b:-}" ]]; then
-      echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
-      missing=1
-    fi
-  done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-  if [[ "$missing" -ne 0 ]]; then
-    echo "hint: run $ws-submodule-setup (and commit .gitmodules), then retry"
-    exit 2
-  fi
-
-  # 强约束：当 .gitmodules 声明 submodules 时，要求本次 change 存在 submodules.targets 且覆盖所有 submodule path
-  if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
-    change_id="$(git branch --show-current | sed -n 's|^change/||p')"
-    targets="changes/${change_id}/submodules.targets"
-    if [[ ! -f "${targets}" ]]; then
-      echo "error: missing ${targets} (required when .gitmodules declares submodules)"
-      exit 2
-    fi
-    t_missing=0
-    while read -r _ sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      if ! awk -v p="${sub_path}" '$1==p && $0 !~ /^[[:space:]]*#/ && $2!="" { found=1 } END { exit(found?0:1) }' "${targets}" 2>/dev/null; then
-        echo "error: ${targets} missing entry for submodule path=${sub_path}"
-        t_missing=1
-      fi
-    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-    if [[ "${t_missing}" -ne 0 ]]; then
-      echo "hint: fill ${targets} as: <path> <target_branch> [remote]"
-      exit 2
-    fi
-  fi
-fi
-```
-
-## A) 发现 submodules 清单（数量不固定）
-在 superproject 根目录执行：
-```bash
-git submodule status --recursive
-```
-如果没有 submodule：跳到 C)。
-
-## B) 逐个提交 submodules（先 submodule，后 superproject）
-对每个 submodule path（可递归）重复以下步骤（建议按 `git submodule status --recursive` 顺序）：
-1) 定位并检查状态：
-```bash
-sub_path="<path>"
-git -C "$sub_path" branch --show-current
-git -C "$sub_path" status --porcelain
-```
-2) 先确定该 submodule 的目标分支来源，并显式说明给用户：
-   - `branch --show-current` 非空：默认建议用当前分支
-   - `branch --show-current` 为空（detached HEAD）：默认建议用 `.gitmodules` 的 `submodule.<name>.branch`
-   - 若建议值与 `changes/<change-id>/submodules.targets` 已落盘值不一致：以 `submodules.targets` 为准，并先提示差异
-3) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
-   - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
-   - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached。
-   - 若你要在该 submodule 里提交：先按目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
-     - 目标分支真值优先级：`changes/<change-id>/submodules.targets`（若存在）> `.gitmodules submodule.<name>.branch`
-```bash
-change_id="<change-id>"
-targets="changes/${change_id}/submodules.targets"
-sub_name="$(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null | awk -v p="${sub_path}" '$2==p { name=$1; sub(/^submodule\\./,"",name); sub(/\\.path$/,"",name); print name; exit }')"
-base_branch="$(python3 - <<'PY'
-import json, pathlib
-change_id = "<change-id>"
-meta = pathlib.Path("changes") / change_id / ".ws-change.json"
-data = json.loads(meta.read_text(encoding="utf-8"))
-print((data.get("base_branch") or "").strip())
-PY
-)"
-test -n "${sub_name}"
-test -n "${base_branch}"
-
-source tools/ws_resolve_sub_target.sh
-ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${base_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
-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
-```
-   - 若 `origin/<target-branch>` 不存在，或用户明确不想使用 pin 分支：停止，解释风险（提交可能不可追溯/难以推送）。
-4) 选择性 staging（默认用 `-p` 更安全）：
-```bash
-git -C "$sub_path" add -p
-git -C "$sub_path" diff --staged --stat
-git -C "$sub_path" diff --staged
-```
-5) AI 生成该 submodule 的 commit message（标题+可选 body），并让用户确认（每个 repo 单独确认）。
-6) 执行提交（不带 `--no-verify`）：
-```bash
-git -C "$sub_path" commit -m "<message>"
-```
-7) 若该 submodule 没有 staged changes：跳过（不要硬提交空 commit）。
-
-## C) 提交 superproject（更新 gitlinks + 自身改动 + changes 工件）
-1) 先检查 submodule 指针差异（gitlinks）：
-```bash
-git diff --submodule
-```
-2) 选择性 staging：
-   - 先 stage 发生指针变化的 submodule 路径（明确列出）：
-```bash
-git add <submodule-path-1> <submodule-path-2>
-```
-   - 再 stage superproject 自身改动（默认 `-p`）：
-```bash
-git add -p
-git diff --staged --stat
-git diff --staged
-```
-3) AI 生成 superproject 的 commit message（应包含 `bump submodule <name> -> <sha>` 等关键信息），并让用户确认。
-4) 提交：
-```bash
-git commit -m "<message>"
-```
-
-## D) 门禁与证据（推荐）
-```bash
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate . --stamp
-elif command -v aiws >/dev/null 2>&1; then
-  aiws validate . --stamp
-else
-  npx @aipper/aiws validate . --stamp
-fi
-```
-
-## D2) 生成持久证据并回填 Evidence_Path（强烈建议）
-> 说明：`.agentdocs/tmp/...` 默认 gitignored；交付前建议把关键结果落到 `changes/<change-id>/evidence/...` 并回填 `proposal.md`/`plan` 的 `Evidence_Path`，避免后续评审/二次会话读不到证据。
-```bash
-change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change evidence "${change_id}"
+  ./node_modules/.bin/aiws deliver
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change evidence "${change_id}"
+  aiws deliver
 else
-  npx @aipper/aiws change evidence "${change_id}"
+  npx @aipper/aiws deliver
 fi
 ```
-
-## D3) 生成状态快照（可选，建议）
-```bash
-aiws change state "${change_id}" --write
-```
-
-## E) 安全合并回目标分支（fast-forward）
-优先使用 `$ws-finish`（底层调用 `aiws change finish`，并在 push 成功后清理对应 change worktree）。
-
-若需要显式指定目标分支：
-```bash
-aiws change finish <change-id> --into <base-branch>
-```
-
-## F) 归档说明
-- 标准链路下不需要再单独执行 `aiws change archive <change-id>`。
-- 进入 `$ws-finish` 并使用 `aiws change finish --push` 时，会自动完成 archive + handoff。
-
-输出要求：
-- `Submodules:` 每个 submodule 的分支/提交摘要（repo → commit sha → message）
-- `Superproject:` 提交摘要
-- `Merge:` `aiws change finish` 的输出（into/from）
-- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
-- `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）