@aipper/aiws-spec 0.0.28 → 0.0.30

package/templates/workspace/.opencode/skills/ws-req-contract-validate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-req-contract-validate
-description: 合同校验（requirements contract validate）
+description: 使用时机：需要校验需求合同完整性时。触发词：合同校验、contract validate、需求核对。注意：合同未同步请先 ws-req-contract-sync。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

package/templates/workspace/.opencode/skills/ws-req-flow-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-req-flow-sync
-description: Flow 同步（生成 api-flow 与场景执行合同）
+description: 使用时机：需要同步 API flow 和场景执行合同时。触发词：flow 同步、api flow、场景合同。注意：flow 定义变更请先 ws-req-change。
 ---
 
 用中文输出；命令与路径保持原样不翻译。

package/templates/workspace/.opencode/skills/ws-req-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-req-review
-description: 需求评审（对齐真值与验收）
+description: 使用时机：需要评审需求、验收条件、合同时。触发词：需求评审、验收评审、合同评审。注意：需求已确认直接进 ws-plan。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

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

@@ -1,11 +1,18 @@
 ---
 name: ws-review
-description: 评审（提交前审计与证据落盘）
+description: 使用时机：需要审计当前改动、查找风险时。触发词：审计、评审、review、风险检查、回归检查。注意：高风险变更应补 ws-spec-review + ws-quality-review。
 ---
 
+## 双审查边界
+
+- `ws-review` 是通用评审入口
+- **高风险或准备 finish 的变更**：必须拆为 `ws-spec-review`（流程/归因/真值完整性）+ `ws-quality-review`（行为回归/边界条件/测试覆盖），两份独立证据
+- 单份 review 文件同时覆盖 spec 和 quality 不计为双审查
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+若当前语境已经明确是“准备交付/finish”，则本入口不应只停留在通用 review：应继续同时补齐 `$ws-spec-review` 与 `$ws-quality-review`，把 dual review gate 一次性收敛完。
 
 OpenCode + oMo 优先策略：
 - 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore` / `librarian`，优先借用这些 agent 做 review。
@@ -14,6 +21,7 @@ OpenCode + oMo 优先策略：
 
 阶段定位：
 - review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
+- 双审查边界：ws-spec-review 查流程/真值归因，ws-quality-review 查行为/回归/测试。高风险或准备 finish 的任务必须同时完成两者。
 
 必需输入：
 - 当前 `git status` / `git diff`
@@ -37,16 +45,39 @@ OpenCode + oMo 优先策略：
 步骤（建议）：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
    - 若检测到 oMo：优先让 `@oracle` 做独立审查；必要时再让 `@explore` / `@librarian` 补上下文。
-2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+1.5) **Triage**：preflight 后立即判断本 change 是否需要双审查：
+   - 需要双审查的条件：改动涉及 REQUIREMENTS 真值、跨 3+ 文件、涉及安全/数据一致性、或准备 finish
+   - 若需要双审查：在步骤 3 开始时即标注 "dual-review: required"，并规划 spec-review + quality-review 两条并行路径
+    - 若不需要双审查：继续通用 review 流程，标注 "dual-review: not-required"
+    - **不得等到 step 6 才决定是否需要双审查**——风险判定必须前置
+   - **Triage 输出格式**：
+     ```
+     Triage: dual-review: required | not-required
+     Rationale: <one reason>
+     Spec review scope: <what to check> (if required)
+     Quality review scope: <what to check> (if required)
+     ```
+   - Findings 格式要求：每个 finding 必须有 [Critical/Warning/Info] 级别标签 + 归因到 SPEC/QUALITY/REGRESSION 类别
+3) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据
    - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
    - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
-3) 将审计落盘到（目录不存在则创建）：
+4) Workflow State Suffix 审计（检查 4 种后缀使用是否一致）：
+   - `session` 后缀：只由 ws-dev-lite / ws-intake 写入，标记会话级进度（如 `[workflow-state:session:in_progress]`）
+   - `gate` 后缀：由 ws-dev / ws-plan-verify 写入，标记计划/实现门禁结果（如 `[workflow-state:gate:plan_passed]`）
+   - `plan` 后缀：由 ws-plan 写入，标记计划阶段状态（如 `[workflow-state:plan:in_progress]`）
+   - `gateway` 后缀：由 ws-finish / ws-deliver 写入，标记交付门禁结果（如 `[workflow-state:gateway:finish_gate_ok]`）
+   - 检查当前 change 中使用的后缀类型是否正确对应所在阶段；若出现混用（如 session 与 gate 在同一文件），在审计报告中标记异常并说明应该修正的方向。
+5) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-4) 回复中输出：
+6) 若 triage 标记为 `dual_review_required`，继续补齐 dual review gate：
+   - 运行/收敛 `$ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`（或回退 `.agentdocs/tmp/review/spec-review.md`）
+   - 运行/收敛 `$ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`（或回退 `.agentdocs/tmp/review/quality-review.md`）
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+7) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

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

@@ -1,6 +1,6 @@
 ---
 name: ws-rule
-description: 规则（解释项目规则与边界）
+description: 使用时机：需要了解项目规则、边界、约束时。触发词：规则、边界、约束、规范、约定。注意：只查询不改代码。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

package/templates/workspace/.opencode/skills/ws-spec-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ws-spec-review
-description: 规范审查（requirements / plan / evidence / gate 完整性）
+description: 使用时机：需要审查流程完整性、requirements 归因时。触发词：规范审查、流程审计、spec review。注意：实现质量审查请用 ws-quality-review。
 ---
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。

package/templates/workspace/.opencode/skills/ws-submodule-setup/SKILL.md

@@ -1,65 +1,18 @@
 ---
 name: ws-submodule-setup
-description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch；减少 detached 与人为差异）
+description: Thin wrapper for `aiws submodule-setup`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-submodule-setup
 
-目标：
-- 为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`，让 `ws-pull` / `ws-finish` 能确定性地“挂回分支/fast-forward push”，避免 origin 多分支时靠猜导致偏差。
-- 该变更是 **superproject 的团队真值**：需要提交 `.gitmodules`。
+Thin skill wrapper. Delegates to `aiws submodule-setup`. See `aiws submodule-setup --help` for details.
 
-安全约束（强制）：
-- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
-- 不在 submodule 中做破坏性操作（不 `reset --hard` / 不改动远端）
-
-步骤（建议）：
-1) 确认工作区干净（否则停止）：
-```bash
-git status --porcelain
-```
-
-2) 列出 submodules（没有则停止并说明无需配置）：
-```bash
-test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
-```
-
-3) 对每个 submodule，输出当前配置与建议分支（让用户确认每个 submodule 的 branch）：
-```bash
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  echo "== submodule: ${name} path=${sub_path} =="
-  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
-  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
-  git -C "${sub_path}" branch -r --list "origin/*" | sed -n '1,30p' || true
-  echo "[choose] set one of:"
-  echo "  - a concrete branch, e.g. main / master / release/x.y"
-  echo "  - '.' to follow superproject current branch name (only if your team uses matching branch names)"
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
-```
-
-4) 逐个写入分支配置（每次写完都回显，避免误配）：
 ```bash
-# Example:
-# git submodule set-branch --branch main path/to/submodule
-# git submodule set-branch --branch .    path/to/submodule
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws submodule-setup
+elif command -v aiws >/dev/null 2>&1; then
+  aiws submodule-setup
+else
+  npx @aipper/aiws submodule-setup
+fi
 ```
-
-5) 输出变更并让用户确认是否提交：
-```bash
-git diff -- .gitmodules
-git status --porcelain
-```
-
-6) 若用户确认要提交：
-```bash
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branches"
-```
-
-输出要求：
-- `Submodules:` name/path + 选择的 branch（每个都列出）
-- `Diff:` `.gitmodules` 的 diff（或至少 `git diff -- .gitmodules` 的摘要）
-- `Next:` 提示后续用 `$ws-pull` 拉取可自动减少 detached；`aiws validate` 会检查该配置是否齐全
-

package/templates/workspace/.opencode/skills/ws-verify-before-complete/SKILL.md

@@ -1,59 +1,49 @@
 ---
 name: ws-verify-before-complete
-description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+description: Thin wrapper for `aiws verify-bc`
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-目标：
-- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
-- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
-
-阶段定位：
-- finish 前 gate；负责 completion readiness 检查，不直接做 merge / push / handoff。
-
-必需输入：
-- `changes/<change-id>/review/spec-review.md`
-- `changes/<change-id>/review/quality-review.md`
-- `.agentdocs/tmp/aiws-validate/*.json`
-- 若存在：`changes/<change-id>/evidence/...`、`git status`
-
-必需输出：
-- `证据（Evidence）:` `changes/<change-id>/evidence/verify-before-complete.md` 或回退 `.agentdocs/tmp/review/verify-before-complete.md`
-- `结论（Result）:` pass / fail
-- `缺失项（Missing）:` 未满足的 gate
-- `下一步（Next）:` 进入 `$ws-finish` / `$ws-handoff`，或回退前置 gate
-
-阻断条件：
-- 缺少 spec review
-- 缺少 quality review
-- 缺少 validate stamp
-- review 中仍有未关闭 blocker
-- 无法写 verification 证据
-
-完成判定：
-- 已落盘 verify-before-complete 证据，并明确能否进入 `$ws-finish` / `$ws-handoff`。
-
-步骤（建议）：
-1) 识别当前 `change/<change-id>`。
-2) 检查以下最小 gate：
-   - `changes/<change-id>/review/spec-review.md`
-   - `changes/<change-id>/review/quality-review.md`
-   - `.agentdocs/tmp/aiws-validate/*.json`
-3) 若存在 `changes/<change-id>/evidence/`，检查是否已经收敛 review / validate / collaboration summary。
-4) 将结果落盘到：
-   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
-   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
-5) 输出：
-   - `证据（Evidence）:`
-   - `结论（Result）: pass|fail`
-   - `缺失项（Missing）:`
-   - `下一步（Next）:`
-
-重点：
-- 这个 gate 不替代 `$ws-finish`；它只判断“是否具备进入 finish / handoff 的前置条件”。
-- 若 fail，必须明确回退到哪个 gate：`$ws-spec-review`、`$ws-quality-review`、`aiws validate . --stamp` 或 `aiws change evidence <change-id>`。
-
-安全：
-- 不打印 secrets。
-- 不执行破坏性命令。
+# ws-verify-before-complete
+
+## 完成前验证 Gate
+
+进入 `ws-finish` / `ws-handoff` 前必须确认：
+
+- [ ] `ws-spec-review` 已完成：`test -f changes/<id>/review/spec-review.md` (→ PASS/FAIL)
+- [ ] `ws-quality-review` 已完成：`test -f changes/<id>/review/quality-review.md` (→ PASS/FAIL)
+- [ ] `aiws validate .` stamp 存在：`ls .agentdocs/tmp/aiws-validate/*.json 2>/dev/null` (→ PASS/FAIL)
+- [ ] 无未关闭 Critical blocker：`grep -c 'Critical' changes/<id>/review/*.md` = 0 或已标记 resolved (→ PASS/FAIL)
+- [ ] 评审-返工循环 handoff 记录：`test -f changes/<id>/handoff-evidence.md` 且含 rework round 记录 (→ PASS/FAIL)
+
+## Gate Result（结构化输出）
+
+```
+Gate: PASS / FAIL
+Items:
+1. spec-review: PASS
+2. quality-review: PASS
+3. validate-stamp: PASS
+4. no-critical-blocker: PASS
+5. rework-handoff: N/A (未经过返工循环)
+Summary: <一句话总结>
+Action: → ws-finish / → 需补齐: <缺失项>
+```
+
+任一项 FAIL 即阻断 finish；输出中必须给出具体缺失项与补救路径。
+
+Thin skill wrapper. Delegates to `aiws verify-bc`. See `aiws verify-bc --help` for details.
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws verify-bc
+elif command -v aiws >/dev/null 2>&1; then
+  aiws verify-bc
+else
+  npx @aipper/aiws verify-bc
+fi
+```
+
+## 执行要求
+
+- 按 Gate Result 结构化输出逐项验证；任一项 FAIL 即阻断 finish。
+- finish 前门禁证据：须确认存在 spec-review.md + quality-review.md（双审查）+ 有效 validate stamp + 已关闭所有 blocker；缺任一项即阻断 finish。

package/templates/workspace/AGENTS.md

@@ -1,88 +1,36 @@
 <!-- AIWS_MANAGED_BEGIN:agents -->
-本仓库启用 AIWS（AI Workspace）约定，请先读取并遵守（按优先级）：
-1) `AI_PROJECT.md`（规则/边界）
-2) `REQUIREMENTS.md`（需求与验收真值）
-3) `AI_WORKSPACE.md`（运行/测试入口真值）
-4) `changes/README.md`（变更工件流程与归档）
-
-最小协作约束：
-- 不确定先跑 `/using-aiws`（Codex 对应 `$using-aiws`）；它会先读真值，再把任务路由到合适的 `ws-*` 入口。
-- 若你已经明确只是做预检，也可以直接跑 `/ws-preflight`（Codex 对应 `$ws-preflight`）；所有实现/修复都以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准。
-- 每次变更建议进入 `change/<change-id>`，并维护 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）。
-- 若仓库存在 `.gitmodules`：优先 `aiws change start <change-id> --worktree`；不要在当前 superproject worktree 里直接切分支。
-- 提交前执行 `aiws validate .`；需要本机门禁时运行 `aiws hooks install .`（或 `git config core.hooksPath .githooks`）。
-- 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等。
-
-标准链路（建议默认）：
-- `using-aiws`：默认 bootstrap/router；先读真值，先判 workflow，再进入具体阶段；意图不明确时先澄清。
-- `ws-preflight`：读取真值文件，输出约束摘要；若真值缺失，先停止，不直接开工。
-- `ws-intake`：计划前置澄清；适用于新需求或中大型变更，按“一题一线程”逐条冻结问题，产出 `plan/*.intake.md` 轻量草案。
-- `ws-plan`：建立 `change/<change-id>` 绑定，落盘 `plan/...`，明确 Verify / Risks / Evidence。
-- `ws-plan-verify`：在编码前做计划质检 + 多视角方案审查；不过门禁就先修 plan，不跳步进实现。
-- `ws-dev`：只做可归因、可验证的小步实现；输出 Changed / Verify / Evidence。
-- `ws-dev-lite`：`ws-dev` 的轻量入口；适用于 simple/local 单点修复，默认不建 `plan/...`、不跑 `ws-plan-verify`，治理归属仍收敛到 `ws-dev`。
-- `ws-delegate`：仅在任务已绑定且 scope 可控时，使用原生多 agent / sub-agent；否则明确降级为单 agent + 协同工件模式。
-- `ws-review`：对当前改动做通用审计；高风险或准备交付时，继续细化到 `ws-spec-review` + `ws-quality-review`。
-- `ws-spec-review`：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
-- `ws-quality-review`：审查行为回归、边界条件、测试覆盖与实现质量。
-- `ws-commit`：串联 review + validate stamp + commit message 确认；不跳过 hooks。
-- `ws-verify-before-complete`：在 finish / handoff 前检查双审查、validate stamp 与交付证据是否齐全。
-- `ws-deliver` / `ws-finish`：做交付收尾、fast-forward 合并、submodule 感知 push，并在完整 finish 后自动归档。
-- `ws-handoff`：查看/补充归档后的 handoff，给下一次会话或下一位协作者接力。
-
-阶段产物（最少）：
-- intake：`plan/*.intake.md`
-- planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
-- implementation：代码 / 配置改动 + Verify 命令记录
-- collaboration：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`
-- review：`changes/<change-id>/review/...` 或回退 `.agentdocs/tmp/review/...`
-- validate：`.agentdocs/tmp/aiws-validate/*.json`
-- handoff / archive：`changes/<change-id>/evidence/...`、`changes/archive/.../handoff.md`
-
-OpenCode（如果你主要用 OpenCode，优先）：
-- native skills 在 `.opencode/skills/`；native commands 在 `.opencode/commands/`
-- 若项目启用了 `.opencode/oh-my-opencode.json`：`ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 会优先借用 oMo 的 `planner-sisyphus` / `explore` / `librarian` / `oracle`
-- 若你想按项目固定这组 agent，可参考 `.opencode/oh-my-opencode.json.example`；它只覆盖 `agents`，不接管 hooks/MCP/LSP
-- 常用手动入口继续保留在 `.opencode/commands/`（migration window 内 `.opencode/command/` 也会保留）；直接使用 `/ws-*`
-- 若你不确定当前任务该先 plan、dev、review 还是 finish：先用 `/using-aiws`
-- 需求还没冻结、想逐条把问题聊清楚：先用 `/ws-intake`
-- `/ws-preflight`：读取真值文件并输出约束摘要
-- `/ws-plan` / `/ws-plan-verify`：先生成计划，再做执行前质检与多视角方案审查
-- `/ws-dev`：常规实现/改配置/改测试
-- `/ws-dev-lite`：小问题直修；若复杂度升高，立刻回到 `/ws-dev` 或 `/ws-plan`
-- `/ws-delegate`：按 AIWS 委托合同拆分子任务，并优先借用 oMo agent
-- `/ws-bugfix`：缺陷修复 + 证据落盘 + CSV 汇总
-- `/ws-review` / `/ws-commit`：提交前审计、门禁与 commit
-- `/ws-spec-review` / `/ws-quality-review`：高风险改动建议显式拆成流程审查 + 质量审查
-- `/ws-verify-before-complete`：finish / handoff 前检查双审查和 validate/evidence
-- `/ws-finish` / `/ws-deliver`：交付收尾（fast-forward / submodule 感知）
-- `/ws-pull` / `/ws-push` / `/ws-submodule-setup`：submodule 场景辅助
-- `/p-aiws-*` 为底层原子入口；模板会同时写入 `.opencode/commands/` 与 `.opencode/command/`，一般不需要直接调用
-
-Claude Code（如果你主要用 Claude Code）：
-- native skills 在 `.claude/skills/`；command-style 兼容入口保留在 `.claude/commands/`
-- 常用链路可按 `ws-*` / `p-aiws-*` 理解；native skills 与 compatibility commands 指向同一套 AIWS workflow
-- 若你不确定当前任务该走哪个阶段：先用 `/using-aiws`
-- 需求还没冻结、想逐条把问题聊清楚：先用 `/ws-intake`
-- 高风险改动或准备 finish 时，建议额外跑 `/ws-spec-review`、`/ws-quality-review`、`/ws-verify-before-complete`
-
-Codex（对应入口，可选）：
-- 若你不想先记住阶段，先用 `$using-aiws` 让 router 判定下一步
-- 对应入口在 `.agents/skills/`；显式调用时使用 `$ws-*`
-- `$using-aiws`
-- `$ws-preflight` / `$ws-intake` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-dev-lite` / `$ws-delegate` / `$ws-frontend-design`
-- `$ws-review` / `$ws-spec-review` / `$ws-quality-review` / `$ws-commit`
-- `$ws-verify-before-complete` / `$ws-finish` / `$ws-deliver`
-- `$ws-pull` / `$ws-push` / `$ws-submodule-setup`
-- 其它入口见 `.agents/skills/`：`ws-*` 为常用链路；`p-*` 为底层原子入口，一般不需要直接调用
-
-Codex 全局入口（可选）：
-- `npx @aipper/aiws codex install-skills`（推荐；安装全局 skills）
-- `npx @aipper/aiws codex install-prompts`（遗留兼容；prompts 已 deprecated）
-
-缺文件或模板漂移时：
-- `npx @aipper/aiws init`（初始化）
-- `npx @aipper/aiws update`（按模板更新托管内容）
+本仓库启用 AIWS（AI Workspace）约定。真值文件（按优先读取）：
+1) `AI_PROJECT.md`（规则/边界）→ 2) `REQUIREMENTS.md`（需求与验收真值）→ 3) `AI_WORKSPACE.md`（运行/测试入口真值）
+
+快速分流：
+- 小修（≤3 文件，≤100 行）→ `/ws-dev-lite`
+- 常规实现 → `/ws-plan` → `ws-dev`
+- 高风险变更 → 加 `ws-spec-review` + `ws-quality-review` 双审查
+- 不确定 → `/using-aiws`（先读真值，再路由）
+
+协作约束：
+- 变更绑定 `change/<id>`，走 plan→verify→dev→review→commit→finish
+- review 完成 → `ws-verify-before-complete` 确认验证通过 → 再 finish
+- review 三方（spec/quality/verify）需 triage 确定是否有 HIGH blocker
+- 主 session 编排收敛，不直接写业务代码；实现与验证由 subagent 产出
+- 提交前 `aiws validate .`；敏感信息不入 git
+- 缺真值文件先 stop，不直接开工
+- handoff 产出 `handoff-evidence.md` 供后续 session 恢复
+
+Red Flags（这些想法都是错的）：
+| 你想的 | 实际 |
+|--------|------|
+| "看着简单直接改" | 简单→ws-dev-lite，不确定→先 /using-aiws |
+| "先动手再说" | 评估先于行动，分流在实现之前 |
+| "跳过 review" | review 是门禁，不是建议 |
+| "主 session 自己写代码" | 编排收敛，subagent 实现 |
+| "不想走流程直接改" | escape-hatch: 可走 ws-dev-lite，但须遵守最小约束（降级需标明） |
+
+阶段产物（最少）：intake=`.aiws/plan/*.intake.md` | planning=`.aiws/plan/...`+`proposal.md`+`tasks.md` | dev=代码+Verify | review=`review/...` | validate=`aiws-validate/*.json` | archive=`evidence/...`+`handoff.md`
+
+平台前缀：OpenCode/Claude=`/` Codex=`$` | 例：`/ws-dev` 或 `$ws-dev`
+Codex 全局安装：`npx @aipper/aiws codex install-skills`
+缺文件/漂移时：`npx @aipper/aiws init` / `npx @aipper/aiws update`
 <!-- AIWS_MANAGED_END:agents -->
 
 你可以在本段下方追加项目自定义说明；`aiws update` 不会改动托管块以外内容。

package/templates/workspace/AI_PROJECT.md

@@ -29,16 +29,16 @@
 ## 3) 产物与证据（强制）
 
 每轮迭代必须落盘至少一个“可追溯产物”（三选一即可）：
-- 证据：`.agentdocs/tmp/...`（report/log/resp）
+- 证据：`.aiws/tmp/...`（report/log/resp）
 - 合同：`issues/*.csv`（状态变化：TODO/DOING/DONE/BLOCKED/SKIP）
-- 变更工件：`changes/<change-id>/`（proposal/tasks/design；详见 `changes/README.md`）
+- 变更工件：`.aiws/changes/<change-id>/`（proposal/tasks/design；详见 `.aiws/changes/README.md`）
 
 不得只在对话里口头描述“已验证/已修复”。
 
 推荐（防规则/范围漂移）：
-- 创建工件：补齐 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
+- 创建工件：补齐 `.aiws/changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
 - 声明 active change（团队共享）：切到分支 `change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若仓库存在 `.gitmodules`：优先使用 `aiws change start <change-id> --worktree`（或至少 `--no-switch`）；不要在当前 superproject worktree 里直接手工切分支。
+- 若仓库存在 `.gitmodules`：使用 `aiws change start <change-id> --switch`；不要在当前 superproject 里直接手工切分支。
 - 若 submodule 因 gitlink checkout 处于 detached HEAD：只允许挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来“解 detached”。
 - 严格校验：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - 启用 hooks（本地生效）：`git config core.hooksPath .githooks`（提交/推送时自动跑 `aiws validate .`）
@@ -74,7 +74,7 @@
 
 - `X-Request-Id`：自动化测试请求必须携带；服务端必须回传同名响应头；日志应包含 `request_id=<id>` 以便按单次请求定位问题。
 - 接口清单真值：优先使用 `docs/openapi.json`。若缺失，先补齐导出方式并生成到该路径，再做全量覆盖测试（避免“覆盖范围不可复现”）。
-- 证据落盘：每轮至少更新一次 `.agentdocs/tmp/...` 或 `issues/*.csv`（禁止只在对话里口头宣称“已验证/已修复”）。
+- 证据落盘：每轮至少更新一次 `.aiws/tmp/...` 或 `issues/*.csv`（禁止只在对话里口头宣称“已验证/已修复”）。
 
 <!-- AIWS_MANAGED_END:ai-project:core -->
 

package/templates/workspace/AI_WORKSPACE.md

@@ -16,7 +16,7 @@
 
 - base_url: "http://127.0.0.1:8080"
 - health_path: "/health"
-- log_path: ".agentdocs/tmp/server-test/app.log"
+- log_path: ".aiws/tmp/server-test/app.log"
 
 - environment: "test"
 - base_url_allowlist:

package/templates/workspace/REQUIREMENTS.md

@@ -71,7 +71,7 @@
 - `issues/server-api-issues.csv`：每个 endpoint 的验收字段与状态机（TODO/DOING/DONE/BLOCKED/SKIP）
 - `issues/server-fix-issues.csv`：当出现 BLOCKED 时自动生成的“下一步修复清单”（用于持续闭环；包含 Failure_Category/Failure_Analysis/Suggestion）
 - `issues/server-triage-issues.csv`：当 runner 无法稳定归因/需要人工判断时生成的“人工介入清单”（避免把噪声混进 fix issues）
-- `.agentdocs/tmp/server-test/`：响应与日志片段（不入库）
+- `.aiws/tmp/server-test/`：响应与日志片段（不入库）
 
 当出现 BLOCKED：
 - 若属于业务/需求不清：先补齐本文件对应接口的期望，再改代码

package/templates/workspace/gitignore

@@ -1,5 +1,5 @@
 # AIWS_MANAGED_BEGIN:gitignore
-.agentdocs/
+.aiws/tmp/
 .aiws/backups/
 secrets/test-accounts.json
 .env