@aipper/aiws-spec 0.0.29 → 0.0.31

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

@@ -7,13 +7,19 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 
 目标：默认入口，先读真值文件，判定当前任务 workflow，再进入具体 `ws-*` skill。若意图不明确：先澄清，不直接进入实现。
 
+## 编排约束
+
+- **不直接实现**：`using-aiws` 自身不是实现阶段；只判 workflow、读真值、路由到对应 `ws-*`。主 session 不直接写代码。
+- **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——具体检查：`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）、`AI_WORKSPACE.md` 中声明的验证命令可行性。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+- **意图不明先澄清**：`routeTo=clarify` 时必须停止并问 1-3 个关键问题，不猜测。
+
 阶段定位：bootstrap/router 阶段；负责分流，不直接完成实现。
 
 ## 必需输入
 
 - 当前任务描述
 - `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
-- 若已存在：`change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+- 若已存在：`change/<change-id>` 上下文、`plan/...`、`.aiws/changes/<change-id>/...`
 
 ## 必需输出
 
@@ -36,24 +42,47 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 - 若未检测到：输出 `standard-opencode`
 - 若缺失任一真值文件 → route = `$ws-preflight`，建议先 `aiws init .`
 
+### 1.5 Per-turn Breadcrumb（必做）
+
+每轮对话开始时强制读取当前 change 状态（`.aiws/changes/<change-id>/.ws-change.json` 或 phase 状态文件），输出 `[workflow-state:PHASE/N]` breadcrumb 标记。
+
+目的：即使 context 被压缩，breadcrumb 也能让 AI 知道当前处于哪个阶段、上次做到哪一步。
+
+格式：`[workflow-state:PHASE_NAME/N]`，其中 PHASE_NAME 取自 standardChain，N 为步骤序号。
+
 ### 2. 路由判定
 
 根据 `packages/spec/docs/workflow-router-rules.json` 判定：
 
+- 路由前先读上下文：判 direct_implementation 前，router 必须先收集项目上下文（git status、涉及文件范围），确认是真正的单文件修复，再决定 direct vs plan。
+
+上下文收集清单（判 direct_implementation 前必须完成）：
+- `git status --porcelain` — 确认未提交改动范围
+- `git diff --stat` — 确认改动文件数量
+- 改动涉及 ≤2 文件且均在已知路径 → 可判 direct
+- 改动涉及 ≥3 文件或含未知路径 → 必须走 ws-plan
+
 | 意图 | Route |
 |------|-------|
 | 需求/验收/合同变更 | `$ws-req-review` |
 | 评审/审计/找风险 | `$ws-review` |
 | finish/merge/push/cleanup | `$ws-finish` |
 | handoff/archive | `$ws-handoff` |
-| 先出设计方案 | `$ws-design` |
-| 更新规范/验收标准 | `$ws-spec-update` |
+| 先出设计方案 | `$ws-plan`（设计作为 plan 阶段一部分） |
+| 更新规范/验收标准 | `$ws-req-change`（需求变更需先 review） |
 | 中大型实现 | `$ws-plan` |
 | 小步明确实现/修复 | `$ws-dev` |
 | 极简修复 | `$ws-dev-lite` |
+| Subagent 不可用 | 回退单 agent + 工件模式 |
 
 注：`$ws-dev` 默认走 subagent-first 策略（详见 `packages/spec/docs/opencode-subagent-first.md`）。主 session 应优先通过 `$ws-delegate` 派发 `aiws-worker`，除非用户明确说"直接改"或"do it inline"。
 
+**Escape Hatch**：若用户明确说"跳过流程"/"直接改"/"do it inline"，允许走 `direct_implementation` 路由，但必须：
+1. 输出 `[escape-hatch: direct-implementation]` 标记
+2. 仍须归因到 Req_ID / Problem_ID
+3. 仍须有可复现验证入口
+4. 仍须落盘 evidence 标记 escape-hatch 使用原因
+
 ### 3. 意图不明确
 
 只问 1-3 个关键问题，明确缺什么（意图、Req_ID/Problem_ID、verify、change 上下文），然后停止。
@@ -82,10 +111,17 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 └──────────────────┴──────────────────────────────────────────────┘
 ```
 
+Subagent 不可用时的降级路径：
+- ready-for-dev 无 subagent → 当前 agent 直接执行 ws-dev（走 inline escape hatch）
+- in-progress 无 reviewer → 当前 agent 自审（走 evaluate-optimize 1 轮）
+- review 无 oracle → 当前 agent 本地 review（不阻断流程）
+
 特殊状态：
 - 上次 delegation 返回 `BLOCKED` → 先解决 blocker 再继续
 - 上次 delegation 返回 `NEEDS_CONTEXT` → 补 context JSONL 后重新派发
 - Subagent-first 默认：`ready-for-dev` / `in-progress` 默认派发 worker/reviewer
+- Subagent 不可用时：降级为当前 agent 直接执行，但必须在 evidence 中记录降级原因
+- Subagent 不可用时回退：单 agent 模式 + 显式维护 `.aiws/changes/<id>/` 工件（handoff-evidence.md, analysis/, patches/）；不阻断流程，但须标注 `mode: single-agent`
 
 ### 5. 输出路由
 
@@ -105,3 +141,4 @@ Next: <继续执行对应 skill，或提出澄清问题>
 - Router 自己不实现代码；不给 route 前不直接改代码
 - 一次只选一个主 route
 - 若复杂度升高：`$ws-dev` 回退到 `$ws-plan`；`$ws-finish` 回退到前置门禁
+- 若 subagent 不可用：回退为单 agent 执行，但须维护与 subagent 模式等价的工件结构（handoff、evidence、review 文件），确保后续 session 可接力

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

@@ -5,7 +5,7 @@ description: 使用时机：需要分析问题、定位根因、收集上下文
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.aiws/tmp/analyze/`。
 
 输入：
 - 主题/需求：用户在本次消息中提供的主题（若不明确，先问一句“本次分析主题是什么？”）
@@ -18,7 +18,7 @@ description: 使用时机：需要分析问题、定位根因、收集上下文
    - 推荐方案（1 个）+ 备选（可选）
    - 风险与回滚（3–8 条）
    - 最小验证命令（可复现）
-3) 将分析落盘到：`.agentdocs/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
+3) 将分析落盘到：`.aiws/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
 4) 回复中必须包含：`Evidence:` 证据文件路径。
 
 安全：

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

@@ -59,4 +59,4 @@ description: 使用时机：需要自主协作、无人值守执行时。触发
 
 安全：
 - `ws-autonomy` 不是 runtime controller。
-- 任何 tmux helper 的结果都必须回收到 `.agentdocs/tmp/opencode-autonomy/`，最终再由主 agent 收敛到 `changes/<id>/...`。
+- 任何 tmux helper 的结果都必须回收到 `.aiws/tmp/opencode-autonomy/`，最终再由主 agent 收敛到 `.aiws/changes/<id>/...`。

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

@@ -7,7 +7,7 @@ description: 使用时机：从禅道/外部系统拉取 bug 进行修复时。
 
 目标：
 - 用禅道 MCP 拉取 bug 详情与附件（尤其图片）
-- 把证据落盘到 `changes/<change-id>/bug/`（避免只停留在对话）
+- 把证据落盘到 `.aiws/changes/<change-id>/bug/`（避免只停留在对话）
 - 把修复任务汇总/更新到 `issues/fix_bus_issues.csv`
 - 与 `ws-dev` / `aiws change` 流程绑定，确保可追溯、可验证
 
@@ -21,7 +21,7 @@ description: 使用时机：从禅道/外部系统拉取 bug 进行修复时。
 2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
 3) 建立 change 上下文（推荐先于任何落盘）：
    - 若当前还不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start`
-   - 工作区必须先干净；否则不要先写 `changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
+   - 工作区必须先干净；否则不要先写 `.aiws/changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
    - 仓库已有提交：优先 `--worktree`
    - superproject + submodule：优先 `--worktree --submodules`
    - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `--no-switch`
@@ -46,7 +46,7 @@ fi
      - 优先复用 `$ws-dev` 的 `submodules.targets` 生成/确认流程
      - detached HEAD 时默认建议取 `.gitmodules` 声明的分支
      - 已附着在某个本地分支时默认建议取当前分支
-     - 以上都只是建议值，最终必须显式写入 `changes/<change-id>/submodules.targets`
+     - 以上都只是建议值，最终必须显式写入 `.aiws/changes/<change-id>/submodules.targets`
 
 建议流程（按顺序）：
 
@@ -58,14 +58,14 @@ fi
 - 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
 
 ## 2) 证据落盘（强制）
-在当前 active change 上下文的 `changes/<change-id>/bug/` 下落盘：
+在当前 active change 上下文的 `.aiws/changes/<change-id>/bug/` 下落盘：
 - `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
 - `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
 - `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
 
 建议目录：
 ```text
-changes/<change-id>/bug/
+.aiws/changes/<change-id>/bug/
   zentao-bug-<bug-id>.json
   zentao-bug-<bug-id>.md
   images/<bug-id>/
@@ -83,7 +83,7 @@ Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Path
 
 字段约束：
 - `Change_ID`：必须等于当前 `change-id`
-- `Evidence_Path`：指向 `changes/<change-id>/bug/zentao-bug-<bug-id>.md`
+- `Evidence_Path`：指向 `.aiws/changes/<change-id>/bug/zentao-bug-<bug-id>.md`
 - `Image_Paths`：多个路径用 `;` 分隔
 - `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
 
@@ -107,5 +107,5 @@ aiws validate . --stamp
 - `Change_ID:` `<change-id>`
 - `Change context:` `<当前分支或 worktree 路径>`
 - `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
-- `Evidence:` `changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
+- `Evidence:` `.aiws/changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
 - `Verify:` 实际运行命令与结果（未运行不声称已运行）

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

@@ -1,18 +1,18 @@
 ---
 name: ws-commit
-description: Thin wrapper for `aiws ws-commit`
+description: Thin wrapper for `aiws commit`
 ---
 
 # ws-commit
 
-Thin skill wrapper. Delegates to `aiws ws-commit`. See `aiws ws-commit --help` for details.
+Thin skill wrapper. Delegates to `aiws commit`. See `aiws commit --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-commit
+  ./node_modules/.bin/aiws commit
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-commit
+  aiws commit
 else
-  npx @aipper/aiws ws-commit
+  npx @aipper/aiws commit
 fi
 ```

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

@@ -7,6 +7,11 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 
 目标：在 OpenCode 中，优先借用 `oh-my-opencode` 的现有 agent 做任务拆分；若 oMo 不可用，再回退为普通 OpenCode delegation / 单 agent 执行。
 
+## 核心约束
+
+- **Subagent-First**：主 session 只做编排与收敛，不直接写实现代码。所有产出必须由 subagent 完成并可追溯到具体 worker。
+- **Handoff 证据**：每轮委托完成后，worker 必须产出结构化 handoff 到 `.aiws/changes/<id>/handoff-evidence.md`（完成项、未完成项、残余风险），供主 session 收敛判断。handoff 文件缺失等同于委托未完成。
+
 ## 必需输入
 
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
@@ -24,12 +29,18 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 - `Evidence:` 产物路径
 - `Next:` 回到 `ws-dev` / `ws-review` / `ws-commit` / `ws-finish`
 
+## 执行要求
+
+- 主 session 不直接改代码：所有实现与验证产物必须由 subagent 产出并向 handoff 记录可追溯
+- handoff 证据：手交材料中须含 delegate round number、产出文件路径、已知未关闭项
+
 ## 阻断条件
 
 - 任务未绑定
 - 没有写清委托边界
 - 上下文策展未执行（未生成 JSONL 或未在 prompt 中引用）
 - 无法判断当前是否可用 oMo，又不能接受回退
+- handoff 文件 `.aiws/changes/<id>/handoff-evidence.md` 缺失或为空（委托返回后必须检查）
 
 ## 角色映射
 
@@ -40,6 +51,16 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 | `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`）：
@@ -61,7 +82,7 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 2. 展开 glob 为实际路径（替换 `<id>`）
 3. 委托者调整：添加/删除/调整 priority/sections
 4. 预算检查：high+medium ≤ 5 文件，总行数 ≤ 4000
-5. 写入 `changes/<id>/analysis/<role>-context.jsonl`
+5. 写入 `.aiws/changes/<id>/analysis/<role>-context.jsonl`
 
 OpenCode 插件 `aiws-inject-context` 会自动注入 JSONL 上下文——只需在 `task()` 中指定 `role: <role>`。
 
@@ -92,16 +113,16 @@ OpenCode 插件 `aiws-inject-context` 会自动注入 JSONL 上下文——只
 - task: <描述>
 - readScope: <文件/目录>
 - writeScope: <文件/目录>
-- artifactTargets: changes/<id>/patches/, changes/<id>/evidence/
+- artifactTargets: .aiws/changes/<id>/patches/, .aiws/changes/<id>/evidence/
 - fallback: single-agent
-Context Curation: changes/<id>/analysis/worker-context.jsonl
+Context Curation: .aiws/changes/<id>/analysis/worker-context.jsonl
 ```
 
 ## 委托者检查清单
 
 派遣前：
 - [ ] 子 agent prompt 包含上下文引用
-- [ ] JSONL 已写入 `changes/<id>/analysis/<role>-context.jsonl`
+- [ ] JSONL 已写入 `.aiws/changes/<id>/analysis/<role>-context.jsonl`
 - [ ] 预算检查通过
 - [ ] readScope / writeScope / artifactTargets 已声明
 
@@ -109,6 +130,7 @@ Context Curation: changes/<id>/analysis/worker-context.jsonl
 - [ ] 解析 Status 行
 - [ ] 非 DONE → 按状态处理规则行动
 - [ ] 非 DONE → 记录决策到 `delegation-decisions.md`
+- [ ] handoff 文件 `.aiws/changes/<id>/handoff-evidence.md` 已存在且非空
 
 安全：
 - 不让 `ws-delegate` 变成第二套 orchestrator

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

@@ -1,18 +1,18 @@
 ---
 name: ws-deliver
-description: Thin wrapper for `aiws ws-deliver`
+description: Thin wrapper for `aiws deliver`
 ---
 
 # ws-deliver
 
-Thin skill wrapper. Delegates to `aiws ws-deliver`. See `aiws ws-deliver --help` for details.
+Thin skill wrapper. Delegates to `aiws deliver`. See `aiws deliver --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-deliver
+  ./node_modules/.bin/aiws deliver
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-deliver
+  aiws deliver
 else
-  npx @aipper/aiws ws-deliver
+  npx @aipper/aiws deliver
 fi
 ```

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

@@ -20,14 +20,35 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 
 - `变更文件（Changed）:` 实际改动清单
 - `验证（Verify）:` 实际运行的命令与结果说明
-- `证据（Evidence）:` `plan/...`、`changes/<change-id>/...`、`.agentdocs/tmp/...` 等证据路径
+- `证据（Evidence）:` `plan/...`、`.aiws/changes/<change-id>/...`、`.aiws/tmp/...` 等证据路径
 - `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
 
-## 阻断条件
+## 前置条件（硬阻断 — 必须最先检查）
 
-- 无法把改动归因到 `REQUIREMENTS.md` 或问题单
-- 没有可复现验证入口
-- 需要创建 change 上下文但当前工作区状态不允许安全切换
+在开始任何代码改动之前，必须完成以下检查：
+
+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 场景。
+
+## TDD 约束（强制）
+
+对于所有需要编写新代码或修改业务逻辑的任务，必须遵守 RED-GREEN-REFACTOR 流程：
+
+1. **RED**：先编写测试用例，运行并确认测试失败（或确认现有测试覆盖缺口）
+2. **GREEN**：编写最小实现代码使测试通过
+3. **REFACTOR**：重构代码，保持测试通过
+
+禁止：
+- 先写实现代码再补测试
+- 跳过测试步骤直接提交
+
+自我检查顺序（每次修改后）：`lint → typecheck → test`。若项目无对应脚本则跳过该项。
 
 ## 完成判定
 
@@ -40,15 +61,24 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 定位项目根目录，读取 `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 中继续。
 
+### 1.5 Spec Refresh（进入实现前必做）
+
+在开始任何代码改动前，强制重读并输出摘要：
+- `AI_PROJECT.md` 安全边界（哪些目录不能动、哪些约束必须遵守）
+- `REQUIREMENTS.md` 中与本次 `Req_ID` 相关的条目（摘要 2-3 段即可）
+
+目的：避免落地时遗忘约束或需求边界。仅需 2-3 段摘要，不需要全文复读。
+
 ### 2. 建立变更归因
 
 - 若 `git status --porcelain` 仅有计划/工件文件，属于预期行为，继续即可。
 - 若需创建新 change：`aiws change start <change-id> --hooks --no-switch`
 - 若需切换分支：先确认无额外未提交改动，再 `git switch change/<change-id>`
-- 若存在 submodule（`.gitmodules`）：进入编码前必须准备好 `changes/<change-id>/submodules.targets`。`aiws change start` 的 `--submodules` 标志会自动处理。参考 `changes/README.md` 和 `changes/<change-id>/submodules.targets` 格式。
+- 若存在 submodule（`.gitmodules`）：进入编码前必须准备好 `.aiws/changes/<change-id>/submodules.targets`。`aiws change start` 的 `--submodules` 标志会自动处理。参考 `changes/README.md` 和 `.aiws/changes/<change-id>/submodules.targets` 格式。
 
 ### 3. 实现策略：默认 dispatch aiws-worker（Subagent-First）
 
@@ -60,6 +90,24 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 - 根据 review 结果决定 fix 或收敛 evidence
 - **Inline escape hatch**：如果用户明确说"你直接改"或"do it inline"，主 session 可直接写代码，但必须落盘 evidence 记录理由
 
+**验证先行推荐**：对于非 trivial 改动，建议先确认验证入口再开始实现：
+1. 先确认 `AI_WORKSPACE.md` 中对应的验证命令
+2. 若验证命令不明确：先补验证入口，再开始实现
+3. 可选模式（不强求 TDD）：先写最小验证 → 实现 → 补完整验证
+
+### 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。
+
 ### 4. 其他规则
 
 - 需求调整：先 `$ws-req-review` → 确认后 `$ws-req-change`

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

@@ -14,8 +14,10 @@ description: 使用时机：单文件/小范围快速修复时。触发词：轻
 适用前提：
 - 目标明确，且能归因到 `Req_ID` 或 `Problem_ID`
 - 验证入口明确，且能做最小可复现验证
-- 一般只影响单文件或紧密相关的小范围文件
+- 一般只影响单文件或紧密相关的小范围文件（≤2 文件，≤100 行）
 - 不需要先改 `REQUIREMENTS.md`，也不需要先单独做 review
+- 仅限以下场景：typo 修复、配置调整、已知回归修复、单点 bugfix
+- 禁止用于：新 feature 开发、跨模块重构、架构变更
 
 立即升级回主流程的情形：
 - 发现任务其实是 medium/complex、跨模块、跨目录或需要方案设计
@@ -25,6 +27,7 @@ description: 使用时机：单文件/小范围快速修复时。触发词：轻
 
 默认约束：
 - 先做 `$ws-preflight`
+- **Escape Hatch**：若用户明确说"跳过流程"/"直接改"，允许 early-start 实现，但必须输出 `[escape-hatch: direct-implementation]` 标记，并仍然遵守最小约束（归因、验证、evidence）
 - 默认不创建 `plan/...`
 - 默认不跑 `$ws-plan-verify`
 - 默认不要求先做双 review
@@ -51,8 +54,8 @@ description: 使用时机：单文件/小范围快速修复时。触发词：轻
    - 若只需局部回归，允许运行更窄的验证，但要说明为什么足够
 6) 留下至少一个可追溯证据：
    - 实际改动文件
-   - 或 `.agentdocs/tmp/...`
-   - 或 `changes/<change-id>/...`
+   - 或 `.aiws/tmp/...`
+   - 或 `.aiws/changes/<change-id>/...`
 7) 输出：
    - `变更文件（Changed）:`
    - `验证（Verify）:`

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

@@ -1,18 +1,22 @@
 ---
 name: ws-finish
-description: Thin wrapper for `aiws ws-finish`
+description: `aiws finish` 的收尾入口（finish_resume_required）
 ---
 
 # ws-finish
 
-Thin skill wrapper. Delegates to `aiws ws-finish`. See `aiws ws-finish --help` for details.
+`aiws finish` 的收尾入口。
+
+关键契约：
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`，继续执行 `aiws change finish <change-id> --push`
+- 普通 finish 的 `validate/evidence/state` 仍应在 `change/<change-id>` worktree 完成，不要在目标 worktree 里跑 `aiws validate . --stamp`
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-finish
+  ./node_modules/.bin/aiws finish
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-finish
+  aiws finish
 else
-  npx @aipper/aiws ws-finish
+  npx @aipper/aiws finish
 fi
 ```

package/templates/workspace/.opencode/skills/ws-frontend-design/SKILL.md

@@ -123,4 +123,4 @@ app-ui 规则：
 - `Visual thesis:` 一句话
 - `Changed:` 改动文件清单
 - `Verify:` 实际运行命令 + 预期结果
-- `Evidence:` 相关 `plan/...`、`changes/<change-id>/...` 或截图/审计路径
+- `Evidence:` 相关 `plan/...`、`.aiws/changes/<change-id>/...` 或截图/审计路径

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

@@ -1,18 +1,18 @@
 ---
 name: ws-handoff
-description: Thin wrapper for `aiws ws-handoff`
+description: Thin wrapper for `aiws handoff`
 ---
 
 # ws-handoff
 
-Thin skill wrapper. Delegates to `aiws ws-handoff`. See `aiws ws-handoff --help` for details.
+Thin skill wrapper. Delegates to `aiws handoff`. See `aiws handoff --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-handoff
+  ./node_modules/.bin/aiws handoff
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-handoff
+  aiws handoff
 else
-  npx @aipper/aiws ws-handoff
+  npx @aipper/aiws handoff
 fi
 ```

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

@@ -10,6 +10,35 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
 - 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论。
 - 产出一份可被 `/ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`。
 
+## 发散-收敛两子阶段
+
+当需求模糊、方向不明确时，intake 分两子阶段推进：
+
+### 发散阶段（Explore）
+- 目标：快速探索 2-3 个可能方向，不深入任何单一方向
+- 输出：每个方向的 1-2 段摘要 + 关键风险 + 依赖
+- 时限：不超过 3 轮对话
+
+### 收敛阶段（Converge）
+- 目标：从发散结果中选择 1 个方向，逐条冻结具体问题
+- 回到标准"一题一线程"模式
+- 把发散产出的摘要作为收敛的输入上下文
+
+触发条件：用户说"不确定"/"多个方向"/"帮我分析" 等模糊表达。
+非模糊需求不需要经过发散阶段，直接进入收敛。
+
+## 核心原则：一次一个问题
+
+- 每轮只推进 1 个 `Open Questions` 中的问题
+- 当前问题未标记 `frozen` 或 `deferred` 前，不进入下一题
+- 输出格式：`Current question → Why it matters → Options → Exit condition`
+- 用户选择后立即写盘更新草案，再进入下一题
+
+**队列保护**：若用户一次提出多个问题，必须显式建队（Queue），逐一处理——不可同时推进多个维度。队列格式：
+- Queue: [Q1: ..., Q2: ..., Q3: ...]
+- Current: Q1
+- Status: [open/in_discussion/frozen/deferred] per item
+
 执行要求：
 1) 先读 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，必要时先 `/ws-preflight`。
 2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
@@ -18,8 +47,9 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
-   - `Exit condition:`
-5) 当前问题在没有被标记成 `frozen` 或 `deferred` 前，不进入下一题。
+    - `Exit condition:`
+- 每个问题独立线程：在未标记 frozen/deferred 前，不进入下一题。问答往返不限轮数，但一次只处理一个维度的决策。
+5) 若用户一次提出多个问题，必须显式排队：列出所有问题编号，按顺序逐个处理；不得同时推进多个问题的讨论。输出格式：`Queued questions: #1, #2, ...  | Current: #1`
 6) 每轮都要把 intake 草案写盘，至少包含：
    - `Context`
    - `Open Questions`

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

@@ -1,18 +1,18 @@
 ---
 name: ws-migrate
-description: Thin wrapper for `aiws ws-migrate`
+description: Thin wrapper for `aiws migrate`
 ---
 
 # ws-migrate
 
-Thin skill wrapper. Delegates to `aiws ws-migrate`. See `aiws ws-migrate --help` for details.
+Thin skill wrapper. Delegates to `aiws migrate`. See `aiws migrate --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-migrate
+  ./node_modules/.bin/aiws migrate
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-migrate
+  aiws migrate
 else
-  npx @aipper/aiws ws-migrate
+  npx @aipper/aiws migrate
 fi
 ```