@aipper/aiws-spec 0.0.41 → 0.0.43

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

@@ -7,60 +7,45 @@ description: 使用时机：从禅道/外部系统拉取 bug 进行修复时。
 
 目标：
 - 用禅道 MCP 拉取 bug 详情与附件（尤其图片）
-- 把证据落盘到 `.aiws/changes/<change-id>/bug/`（避免只停留在对话）
-- 把修复任务汇总/更新到 `issues/fix_bus_issues.csv`
+- 证据落盘到 `.aiws/changes/<change-id>/bug/`（避免只停留在对话）
+- 汇总/更新到 `issues/fix_bus_issues.csv`
 - 与 `ws-dev` / `aiws change` 流程绑定，确保可追溯、可验证
 
-非目标（强制）：
-- 不自动 commit / push
-- 不写入任何 secrets（token、cookie、内网地址）
-- 不在无法复现时直接改代码（先产出阻塞信息）
+非目标（强制）：不自动 commit/push；不写入 secrets（token、cookie、内网地址）；不在无法复现时直接改代码（先产出阻塞信息）。
 
 前置：
-1) 先运行 `$ws-preflight`。
-2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
+1) 运行 `$ws-preflight`。
+2) 准备 `change-id`（建议 `bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
 3) 建立 change 上下文（推荐先于任何落盘）：
-   - 若当前还不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start`
-   - 工作区必须先干净；否则不要先写 `.aiws/changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
-   - 仓库已有提交：优先 `--worktree`
-   - superproject + submodule：优先 `--worktree --submodules`
-   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `--no-switch`
-```bash
-if [[ -n "$(git status --porcelain)" ]]; then
-  echo "error: working tree dirty before ws-bugfix creates change context"
-  exit 2
-fi
-
-if git rev-parse --verify HEAD >/dev/null 2>&1; then
-  if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
-    aiws change start <change-id> --hooks --worktree --submodules
-  else
-    aiws change start <change-id> --hooks --worktree
-  fi
-else
-  aiws change start <change-id> --hooks --no-switch
-fi
-```
-   - 若上一步创建了 worktree：后续 bug 证据、CSV 更新、`$ws-dev` 修复都必须在该 worktree 中继续；不要回原工作区重复创建 change
-   - 若该 change 涉及 submodule：
-     - 优先复用 `$ws-dev` 的 `submodules.targets` 生成/确认流程
-     - detached HEAD 时默认建议取 `.gitmodules` 声明的分支
-     - 已附着在某个本地分支时默认建议取当前分支
-     - 以上都只是建议值，最终必须显式写入 `.aiws/changes/<change-id>/submodules.targets`
+   - 工作区必须先干净；不要先写 bug 文件或 CSV，避免后续切 worktree 时工件留在原工作区
+   - 工作树策略：
+     ```bash
+     if [[ -n "$(git status --porcelain)" ]]; then
+       echo "error: dirty before ws-bugfix"; exit 2
+     fi
+     if git rev-parse --verify HEAD >/dev/null 2>&1; then
+       if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\..*\.path$' >/dev/null 2>&1; then
+         aiws change start <change-id> --hooks --worktree --submodules
+       else
+         aiws change start <change-id> --hooks --worktree
+       fi
+     else
+       aiws change start <change-id> --hooks --no-switch
+     fi
+     ```
+   - 若创建了 worktree：后续所有操作必须在该 worktree 中继续
+   - 涉及 submodule：确认 `submodules.targets` 已写入（复用 `$ws-dev` 流程）
 
-建议流程（按顺序）：
+建议流程：
 
 ## 1) 通过禅道 MCP 拉取 bug
-- 使用当前会话中已启用的 zentao MCP 工具获取：
-  - `bug_id`、标题、优先级/严重级、模块、状态、指派人
-  - 重现步骤、期望结果、实际结果
-  - 附件列表（含图片 URL/文件名）
-- 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
+- 使用当前会话中的 zentao MCP 获取：`bug_id`、标题、优先级/严重级、模块、状态、指派人、重现步骤、期望结果、实际结果、附件列表
+- 若没有 zentao MCP：立即停止并提示用户先配置，不要猜数据
 
 ## 2) 证据落盘（强制）
-在当前 active change 上下文的 `.aiws/changes/<change-id>/bug/` 下落盘：
-- `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
-- `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
+在 `.aiws/changes/<change-id>/bug/` 下落盘：
+- `zentao-bug-<bug-id>.json`：原始字段快照
+- `zentao-bug-<bug-id>.md`：人类可读摘要（复现/期望/实际/风险）
 - `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
 
 建议目录：
@@ -72,36 +57,25 @@ fi
 ```
 
 ## 3) 汇总到 issues/fix_bus_issues.csv（upsert）
-- 目标文件：当前 active change 上下文中的 `issues/fix_bus_issues.csv`
-- 若文件不存在，先创建表头：
+
+目标文件：`issues/fix_bus_issues.csv`。不存在则创建表头：
 ```csv
 Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Paths,Evidence_Path,Verify_Command,Fix_Status,Updated_At,Notes
 ```
-- 以 `Bug_ID` 为主键 upsert：
-  - 已存在：更新状态/证据/图片路径
-  - 不存在：新增一行
-
-字段约束：
-- `Change_ID`：必须等于当前 `change-id`
-- `Evidence_Path`：指向 `.aiws/changes/<change-id>/bug/zentao-bug-<bug-id>.md`
-- `Image_Paths`：多个路径用 `;` 分隔
-- `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
+以 `Bug_ID` 为主键 upsert：已存在则更新状态/证据/图片路径；不存在则新增。
+字段约束：`Change_ID` = 当前 change-id；`Evidence_Path` 指向 `.md`；`Image_Paths` 用 `;` 分隔；`Fix_Status` 为 `TODO|DOING|DONE|BLOCKED`。
 
 ## 4) 修复执行与回填
-- 进入 `$ws-dev` 做最小改动修复；若 `ws-bugfix` 创建了 worktree，则必须在该 worktree 中继续。
-- 完成后回填 `issues/fix_bus_issues.csv`：
-  - `Fix_Status`
-  - `Verify_Command`
-  - `Updated_At`
-  - `Notes`（必要时写阻塞原因）
+- 进入 `$ws-dev` 做最小改动修复（若 `ws-bugfix` 创建了 worktree，必须在该 worktree 中继续）
+- 完成后回填 CSV：`Fix_Status`、`Verify_Command`、`Updated_At`、`Notes`
 
 ## 5) 验证与交付
+
 ```bash
 aiws change validate <change-id> --strict
 aiws validate . --stamp
 ```
-- 需要提交时走 `$ws-commit`。
-- 需要收尾合并时走 `$ws-finish`（或在 superproject + submodule 场景走 `$ws-deliver`）。
+- 提交走 `$ws-commit`；收尾合并走 `$ws-finish`（superproject + submodule 场景走 `$ws-deliver`）
 
 输出要求：
 - `Change_ID:` `<change-id>`
@@ -109,3 +83,5 @@ aiws validate . --stamp
 - `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
 - `Evidence:` `.aiws/changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
 - `Verify:` 实际运行命令与结果（未运行不声称已运行）
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

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

@@ -5,114 +5,85 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：在 OpenCode 中，优先借用 `oh-my-opencode` 的现有 agent 做任务拆分；若 oMo 不可用，再回退为普通 OpenCode delegation / 单 agent 执行。
+目标：优先借用 oMo agent 做任务拆分；若不可用，回退普通 OpenCode delegation / 单 agent。
 
 ## 核心约束
 
-- **Subagent-First**：主 session 只做编排与收敛，不直接写实现代码。所有产出必须由 subagent 完成并可追溯到具体 worker。
-- **Handoff 证据**：每轮委托完成后，worker 必须产出结构化 handoff 到 `.aiws/changes/<id>/handoff-evidence.md`（完成项、未完成项、残余风险），供主 session 收敛判断。handoff 文件缺失等同于委托未完成。
+- **Subagent-First**：主 session 只做编排收敛，不直接写代码。所有产出由 subagent 完成并可追溯。
+- **Handoff 证据**：worker 必须产出 `.aiws/changes/<id>/handoff-evidence.md`（完成项、未完成项、残余风险）。文件缺失=委托未完成。
 
 ## 必需输入
 
-- 真值文件：`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`
+- 真值文件 + delegation contract 等上下文（`workflow-delegation-contracts.md`、`opencode-omo-adapter.md`、`opencode-subagent-first.md`）
 - 当前任务已绑定 `Req_ID` / change / Verify
 
 ## 必需输出
 
 - `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`
+- `Context Curation:` 策展详情 / `Execution Mode:` / `Evidence:` / `Next:`
 
 ## 执行要求
 
-- 主 session 不直接改代码：所有实现与验证产物必须由 subagent 产出并向 handoff 记录可追溯
-- handoff 证据：手交材料中须含 delegate round number、产出文件路径、已知未关闭项
+- 主 session 不直接改代码；所有产物由 subagent 产出且可追溯
+- handoff 含 delegate round number、产出文件路径、已知未关闭项
 
 ## 阻断条件
 
-- 任务未绑定
-- 没有写清委托边界
-- 上下文策展未执行（未生成 JSONL 或未在 prompt 中引用）
-- 无法判断当前是否可用 oMo，又不能接受回退
-- handoff 文件 `.aiws/changes/<id>/handoff-evidence.md` 缺失或为空（委托返回后必须检查）
+任务未绑定 / 委托边界不清 / 上下文策展未执行 / 无法判断 oMo 可用性 / handoff 文件缺失
 
 ## 角色映射
 
 | aiws 角色 | oMo Agent |
 |-----------|-----------|
-| `planner` | `planner-sisyphus` |
-| `explorer` | `@explore` / `@librarian` |
-| `reviewer` | `@oracle` |
-| `integrator` | 当前主 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 |
+| 角色 | 职责 | 读取 | 写入 |
+|------|------|------|------|
+| 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 详情，不继续
+2. 检查返回状态（DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED）
+3. DONE → dispatch `aiws-reviewer`；pass→收敛 evidence；fail→worker 修复（≤3 次）
+4. DONE_WITH_CONCERNS → 先 `ws-quality-review`
+5. NEEDS_CONTEXT → 补上下文重试（≤2 次）；仍失败→回退单 agent
+6. 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
+1. 读取合同基线的 `contextFiles`
+2. 展开 glob（替换 `<id>`）
+3. 委托者调整（添加/删除/调整 priority/sections）
+4. 预算检查：high+medium ≤5 文件，总行数 ≤4000
 5. 写入 `.aiws/changes/<id>/analysis/<role>-context.jsonl`
 
-OpenCode 插件 `aiws-inject-context` 会自动注入 JSONL 上下文——只需在 `task()` 中指定 `role: <role>`。
+插件 `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:** 疑虑或未完成项
+**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: <文件/目录>
+- role: worker | preferred agent: aiws-worker
+- readScope: <...> | writeScope: <...>
 - artifactTargets: .aiws/changes/<id>/patches/, .aiws/changes/<id>/evidence/
 - fallback: single-agent
 Context Curation: .aiws/changes/<id>/analysis/worker-context.jsonl
@@ -120,19 +91,13 @@ Context Curation: .aiws/changes/<id>/analysis/worker-context.jsonl
 
 ## 委托者检查清单
 
-派遣前：
-- [ ] 子 agent prompt 包含上下文引用
-- [ ] JSONL 已写入 `.aiws/changes/<id>/analysis/<role>-context.jsonl`
-- [ ] 预算检查通过
-- [ ] readScope / writeScope / artifactTargets 已声明
+派遣前：`[ ] prompt 含上下文引用` `[ ] JSONL 已写入` `[ ] 预算检查通过` `[ ] readScope/writeScope/artifactTargets 已声明`
 
-返回后：
-- [ ] 解析 Status 行
-- [ ] 非 DONE → 按状态处理规则行动
-- [ ] 非 DONE → 记录决策到 `delegation-decisions.md`
-- [ ] handoff 文件 `.aiws/changes/<id>/handoff-evidence.md` 已存在且非空
+返回后：`[ ] 解析 Status` `[ ] 非 DONE→按规则处理` `[ ] 非 DONE→记录决策到 delegation-decisions.md` `[ ] handoff 文件存在且非空`
 
 安全：
 - 不让 `ws-delegate` 变成第二套 orchestrator
 - 不让 delegated agent 越权写未授权文件
 - 不跳过 submodule drift check（若 `.gitmodules` 存在）
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

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

@@ -19,105 +19,71 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 ## 必需输出
 
 - `变更文件（Changed）:` 实际改动清单
-- `验证（Verify）:` 实际运行的命令与结果说明
-- `证据（Evidence）:` `plan/...`、`.aiws/changes/<change-id>/...`、`.aiws/tmp/...` 等证据路径
+- `验证（Verify）:` 实际运行的命令与结果
+- `证据（Evidence）:` `plan/...`、`.aiws/changes/<change-id>/...` 等证据路径
 - `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
 
 ## 前置条件（硬阻断 — 必须最先检查）
 
-在开始任何代码改动之前，必须完成以下检查：
+1. **Design Gate**：若 `proposal.md` 不存在 → 立即停止，输出 `BLOCKED: 缺少 proposal。请先执行 $ws-plan`
+2. **Task Gate**：若 `tasks.md` 不存在 → 立即停止，输出 `BLOCKED: 缺少 tasks。请先执行 $ws-plan`
+3. **Granularity Gate**：对每个 task 估算原子操作数（read/edit/write/run）。若任一 task 需 >3 原子操作 → 立即停止，返回 `$ws-plan` 拆细后再进入。
 
-1. **Design Gate**：若 `.aiws/changes/<change-id>/proposal.md` 不存在：
-   - 立即停止，不要写代码
-   - 输出：`BLOCKED: 缺少 proposal。请先执行 $ws-plan 创建变更计划与任务分解。`
-2. **Task Gate**：若 `.aiws/changes/<change-id>/tasks.md` 不存在：
-   - 立即停止，不要写代码
-   - 输出：`BLOCKED: 缺少 tasks。请先执行 $ws-plan 创建任务分解。`
-
-> 例外：`ws-dev-lite` 是轻量入口，可豁免 Design Gate，但仅限单文件/typo/config/bugfix 场景。
+> 例外：`ws-dev-lite` 可豁免 Design Gate，仅限单文件/typo/config/bugfix 场景。
 
 ## TDD 约束（强制）
 
-对于所有需要编写新代码或修改业务逻辑的任务，必须遵守 RED-GREEN-REFACTOR 流程：
-
-1. **RED**：先编写测试用例，运行并确认测试失败（或确认现有测试覆盖缺口）
-2. **GREEN**：编写最小实现代码使测试通过
-3. **REFACTOR**：重构代码，保持测试通过
-
-禁止：
-- 先写实现代码再补测试
-- 跳过测试步骤直接提交
-
-自我检查顺序（每次修改后）：`lint → typecheck → test`。若项目无对应脚本则跳过该项。
+对于编写新代码或修改业务逻辑的任务，必须遵守 RED-GREEN-REFACTOR：
+1. **RED**：先写测试，运行并确认测试失败
+2. **GREEN**：最小实现使测试通过
+3. **REFACTOR**：重构，保持测试通过
+禁止：先写实现再补测试 / 跳过测试直接提交。
+修改后自检：`lint → typecheck → test`（项目无对应脚本则跳过）。
 
 ## 完成判定
 
-改动已落盘、验证已执行或明确未执行原因、证据路径可回放，并可进入 review/commit 阶段。
+改动已落盘、验证已执行或已说明未执行原因、证据路径可回放，可进入 review/commit。
 
 ## 建议流程
 
 ### 1. Preflight
 
-定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
-
-- 中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件。
-- 中大型任务默认执行 [3.1 自我修正循环](#31-自我修正循环evaluate-optimize)——这是必经步骤，不是可选项：实现后先自审修正（最多 2 轮），再进入 review
-- 已有计划：先 `$ws-plan-verify`，通过后进入实现。
-- `$ws-plan` 已创建 worktree：直接在该 worktree 中继续。
+定位项目根，读取真值文件，输出约束摘要。
+- 中大型任务：先用 `$ws-plan` 生成 `plan/` 工件，并默认执行 3.1 自我修正循环
+- 已有计划：先 `$ws-plan-verify`，通过后进入实现
+- `$ws-plan` 已创建 worktree：直接在其中继续
 
 ### 1.5 Spec Refresh（进入实现前必做）
 
-在开始任何代码改动前，强制重读并输出摘要：
-- `AI_PROJECT.md` 安全边界（哪些目录不能动、哪些约束必须遵守）
-- `REQUIREMENTS.md` 中与本次 `Req_ID` 相关的条目（摘要 2-3 段即可）
-
-目的：避免落地时遗忘约束或需求边界。仅需 2-3 段摘要，不需要全文复读。
+重读 `AI_PROJECT.md` 安全边界和 `REQUIREMENTS.md` 相关条目，输出 2-3 段摘要。避免遗忘约束或需求边界。
 
 ### 2. 建立变更归因
 
-- 若 `git status --porcelain` 仅有计划/工件文件，属于预期行为，继续即可。
-- 若需创建新 change：`aiws change start <change-id> --hooks --no-switch`
-- 若需切换分支：先确认无额外未提交改动，再 `git switch change/<change-id>`
-- 若存在 submodule（`.gitmodules`）：进入编码前必须准备好 `.aiws/changes/<change-id>/submodules.targets`。`aiws change start` 的 `--submodules` 标志会自动处理。参考 `changes/README.md` 和 `.aiws/changes/<change-id>/submodules.targets` 格式。
+- `git status --porcelain` 仅有计划/工件文件 → 继续
+- 创建新 change：`aiws change start <change-id> --hooks --no-switch`
+- 切换分支：先确认无未提交改动，再 `git switch change/<change-id>`
+- 有 submodule：准备好 `submodules.targets`（`--submodules` 标志自动处理）
 
 ### 3. 实现策略：默认 dispatch aiws-worker（Subagent-First）
 
-详细执行循环见 `packages/spec/docs/opencode-subagent-first.md`。
-
-- 主 session **默认不直接写实现代码**；通过 `$ws-delegate` 派发 `aiws-worker`
-- `task()` 调用中指定 `role: worker`，让 `aiws-inject-context` 插件自动注入 JSONL 上下文
-- worker 返回后，派发 `aiws-reviewer` 做独立审查
-- 根据 review 结果决定 fix 或收敛 evidence
-- **Inline escape hatch**：如果用户明确说"你直接改"或"do it inline"，主 session 可直接写代码，但必须落盘 evidence 记录理由
-
-**验证先行推荐**：对于非 trivial 改动，建议先确认验证入口再开始实现：
-1. 先确认 `AI_WORKSPACE.md` 中对应的验证命令
-2. 若验证命令不明确：先补验证入口，再开始实现
-3. 可选模式（不强求 TDD）：先写最小验证 → 实现 → 补完整验证
+详见 `packages/spec/docs/opencode-subagent-first.md`。
+- 主 session **默认不直接写代码**；通过 `$ws-delegate` 派发 `aiws-worker`（`task()` 中加 `role: worker`）
+- worker 返回后派发 `aiws-reviewer` 独立审查，根据结果 fix 或收敛 evidence
+- **Inline escape hatch**：用户说"直接改"或"do it inline"时可直接写代码，但必须落盘记录理由
+- 验证先行：先确认 `AI_WORKSPACE.md` 中验证命令；不明确则先补验证入口再实现
 
 ### 3.1 自我修正循环（evaluate-optimize）——必经步骤
 
-在 dispatch subagent 前，主 session 必须执行最多 **2 轮** 自审+修正循环：
-
-1. **实现** → subagent 产出代码
-2. **自审** → 主 session 检查：lint/type-check 是否通过？是否符合现有代码模式？是否有明显 bug？
-3. **修正** → 如果发现问题，要求 subagent 修正后重新提交
-4. **2 轮上限** → 如果 2 轮后仍有问题，升级到 `$ws-review` 做正式审查
-
-**适用场景**：所有非 trivial 改动（单文件修复、配置调整、小步实现、中大型任务均适用）。不适合跨模块架构变更——此类变更直接走 $ws-review。
-
-**注意**：这不是替代 `$ws-review` 的门禁；自审通过后仍需走正式 review gate。
+dispatch 前最多 **2 轮** 自审+修正：subagent 产出 → 主 session 检查（lint/typecheck/代码模式）→ 有问题则要求修正 → 2 轮后仍有问题升级到 `$ws-review`。
+适用：所有非 trivial 改动。注意：不替代 `$ws-review` 正式 gate。
 
 ### 4. 其他规则
 
-- 需求调整：先 `$ws-req-review` → 确认后 `$ws-req-change`
-- 最小改动：每处改动必须归因到 `REQUIREMENTS.md` 或 `issues/problem-issues.csv`
-- 验证：运行 `AI_WORKSPACE.md` 声明的命令；未运行不声称已运行
-- 多步任务：使用 `update_plan` 工具跟踪状态
-- 提交前门禁：
-  ```bash
-  aiws validate .
-  ```
+- 需求调整：`$ws-req-review` → 确认后 `$ws-req-change`
+- 最小改动：每处改动归因到 `REQUIREMENTS.md` 或 `issues/problem-issues.csv`
+- 验证：运行 `AI_WORKSPACE.md` 命令；未运行不声称已运行
+- 多步任务用 `update_plan` 跟踪
+- 提交前门禁：`aiws validate .`
 - 交付收尾：`$ws-finish`
 
 ## 输出要求
@@ -125,3 +91,5 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 - `变更文件（Changed）:` 文件清单
 - `验证（Verify）:` 实际运行的命令 + 期望结果
 - `证据（Evidence）:` 证据路径
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

package/templates/workspace/.opencode/skills/ws-dev-lite/SKILL.md

@@ -72,3 +72,5 @@ Workflow State Suffix（会话门禁约定）：
 - `gate` 后缀保留给 `ws-dev` / `ws-plan-verify` 的完整计划门禁；不要在本 skill 中使用 `gate` 后缀。
 - 若需要与 `ws-dev` 共享状态：先通过 `$ws-dev` 建立 `gate` 后缀记录，再回到 lite 修复。
 - 详细参见 `ws-dev` 的 Workflow State Suffix 约定。
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`