@aipper/aiws-spec 0.0.51 → 0.0.53

package/templates/workspace/.opencode/commands/ws-quality-review.md

@@ -1,30 +0,0 @@
----
-description: 质量审查：行为回归 / 测试覆盖 / 实现质量
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-quality-review -->
-# ws quality review
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-目标：审查行为回归、边界条件、测试覆盖与实现质量。
-
-步骤（建议）：
-1) 读取 `git diff`、已执行的验证结果和相关代码。
-   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `explore`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
-   - 质量/回归审查优先 `@oracle`；代码路径与影响面补充优先 `@explore`。
-2) 检查：
-   - 是否存在行为回归或明显 bug 风险
-   - 边界条件 / 失败路径是否覆盖
-   - 测试是否足以支撑当前改动
-3) 将结论落盘到：
-   - 默认：`changes/<change-id>/review/quality-review.md`
-   - 回退：`.agentdocs/tmp/review/quality-review.md`
-4) 输出：
-   - `证据（Evidence）:`
-   - `主要发现（Findings）:`
-   - `测试缺口（Gaps）:`
-   - `下一步（Next）:`
-5) 若 oMo 不可用：回退为当前 agent 本地 quality review。
-<!-- AIWS_MANAGED_END:opencode:ws-quality-review -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-change.md

@@ -1,45 +0,0 @@
----
-description: 需求变更：更新 REQUIREMENTS 并同步执行合同
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-change -->
-# ws req change
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-目标：记录需求变更（更新 `REQUIREMENTS.md` + 追加 `requirements/CHANGELOG.md`），并同步/校验执行合同 `requirements/requirements-issues.csv`。
-
-步骤（必须按顺序）：
-1) 读取：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`requirements/CHANGELOG.md`（缺失则创建目录与文件）。
-2) 先产出“拟变更方案”（不要立刻写文件）：
-   - 变更摘要（1–5 条）
-   - 影响范围（API/鉴权/字段/状态码/测试边界）
-   - 回滚思路（1–2 条）
-3) 对比与冲突检查（强制，不写文件）：
-   - 对比“变更前 vs 拟变更后”的差异清单（新增/删除/语义变化）
-   - 整理潜在冲突/不确定点（只列“最可能影响验收/实现”的，避免噪音）
-4) 逐条澄清（强制，避免一次问完）：
-   - 若存在潜在冲突/不确定点：**本轮只问 1 个**最高优先级问题（给出 2–4 个可选答案或二选一），然后停止，等待用户回复；不要继续问下一题，也不要写文件。
-   - 收到用户回复后：更新“拟变更方案”，回到步骤 3) 重新对比，直至没有未决问题。
-5) 强制停下来让用户确认：是否继续落盘？(Y/N)
-6) 用户确认 Y 后再写入：
-   - 更新 `REQUIREMENTS.md`（只保留当前有效版本，不在此堆历史）
-   - 追加 `requirements/CHANGELOG.md`
-7) 同步/补齐需求执行合同（强制，自动处理 FlowSpec 有/无两种情况）：
-   - `python3 tools/requirements_contract_sync.py --workspace .`
-   - 说明：若 `REQUIREMENTS.md` 中不存在 FlowSpec（或 flows 为空），该命令只会确保 `requirements/requirements-issues.csv` 表头存在并给出 WARN（这是预期行为，不要当成失败）。
-8) 校验需求执行合同（强制）：`python3 tools/requirements_contract.py validate`
-9) 同步场景合同（可选，但若存在 FlowSpec 则强烈建议自动执行）：
-   - 若 `REQUIREMENTS.md` 同时包含 `<!-- FLOW_SPEC_BEGIN -->` 与 `<!-- FLOW_SPEC_END -->`：运行 `/ws-req-flow-sync`
-   - 否则：跳过，并提示用户“可以先不维护 FlowSpec；后续需要场景回归时再补”
-
-输出必须包含：
-- 本次更新的文件清单（路径）
-- 回滚方案（如何撤销本次需求变更）
-- 下一步建议命令
-
-安全：
-- 不打印 `secrets/test-accounts.json`
-- 不引入任何 token/密钥到仓库
-<!-- AIWS_MANAGED_END:opencode:ws-req-change -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-contract-sync.md

@@ -1,21 +0,0 @@
----
-description: 合同同步：把 REQUIREMENTS FlowSpec 同步到 requirements-issues.csv
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-sync -->
-# ws req contract sync
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-用途：从 `REQUIREMENTS.md` 的 FlowSpec 补齐 `requirements/requirements-issues.csv`（只生成骨架，不猜测完成状态）。
-
-执行（在 workspace 根目录）：
-- `python3 tools/requirements_contract_sync.py --workspace .`
-
-输出要求：
-- 说明新增/更新了多少条
-- 明确下一步：手工补齐 CRUD/Inputs/Outputs/Business_Logic/Tests，并将可开工条目标为 `Spec_Status=READY`
-
-下一步建议：`/ws-req-contract-validate`
-<!-- AIWS_MANAGED_END:opencode:ws-req-contract-sync -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -1,16 +0,0 @@
----
-description: 合同校验：校验 requirements-issues.csv 字段完整性
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-validate -->
-# ws req contract validate
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-执行（失败则修正 CSV 后重试）：
-- `python3 tools/requirements_contract.py validate`
-
-输出要求：
-- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议
-<!-- AIWS_MANAGED_END:opencode:ws-req-contract-validate -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -1,23 +0,0 @@
----
-description: Flow 同步：从 REQUIREMENTS 生成 api-flow 与场景执行合同
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-flow-sync -->
-# ws req flow sync
-
-用中文输出；命令与路径保持原样不翻译。
-
-目标：基于 `REQUIREMENTS.md` 的 FlowSpec 生成：
-- `docs/api-flow.mmd`（简短逻辑图，Mermaid）
-- `issues/server-scenario-issues.csv`（场景执行合同：TODO/DONE/BLOCKED）
-
-执行（在 workspace 根目录）：
-`python3 tools/requirements_flow_gen.py --workspace .`
-
-若缺少工具 `tools/requirements_flow_gen.py`：提示用户先运行 `npx @aipper/aiws init .`（默认会安装 optional tools）。
-
-输出要求：只打印生成的文件路径与下一步命令：
-- 查看逻辑图：`cat docs/api-flow.mmd`
-- 查看场景合同：`cat issues/server-scenario-issues.csv`
-<!-- AIWS_MANAGED_END:opencode:ws-req-flow-sync -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-review.md

@@ -1,36 +0,0 @@
----
-description: 需求评审：对 REQUIREMENTS 做整体 QA（不改文件）
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-review -->
-# ws req review
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
-
-执行步骤（强制）：
-1) 定位项目根目录：先尝试 `git rev-parse --show-superproject-working-tree`（submodule 感知上溯）；若为空再用 `git rev-parse --show-toplevel`。都失败则停止并让用户确认根目录。
-2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
-   - `AI_PROJECT.md`
-   - `REQUIREMENTS.md`
-   - `AI_WORKSPACE.md`
-   - `requirements/CHANGELOG.md`（若存在）
-   - `requirements/requirements-issues.csv`（若存在）
-3) 输出固定结构的报告：
-
-## Requirements QA
-- 结论：是否可进入实现（是/否/有条件）
-- 漂移风险：最容易导致不一致的点
-- 可验收性缺口：缺少输入/输出/错误码/边界/示例的条目
-- 完整性：Non-goals/兼容性/鉴权/重试/并发/观测性/性能
-- 一致性：与 `AI_PROJECT.md` 约束冲突点
-- 可测试性与证据：最小验证命令 + 期望结果 + 证据路径
-- 风险清单：3–8 条
-- 需要澄清的问题：5–12 个（按优先级）
-
-4) 最后询问用户：是否进入需求落盘流程 `/ws-req-change`？(Y/N)
-
-安全：不打印 `secrets/test-accounts.json`。
-<!-- AIWS_MANAGED_END:opencode:ws-req-review -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-rule.md

@@ -1,27 +0,0 @@
----
-description: 规则：把口述规则整理并写入 AI_PROJECT.md 托管段
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-rule -->
-# ws rule
-
-     用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-     目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
-
-     安全规则（强制）：
-     - 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
-     - 不执行破坏性命令。
-
-     工作流：
-     1) 先运行 `/ws-preflight`；若缺失 `AI_PROJECT.md`：提示用户先 `/ws-migrate` 或运行 `npx @aipper/aiws init .`。
-     2) 写入前创建备份（必须）：
-`ts="$(date +%Y%m%d-%H%M%S)"; mkdir -p .aiws/backups/manual; cp -a AI_PROJECT.md .aiws/backups/manual/AI_PROJECT.md.bak.${ts}`
-     3) 先输出“将写入的规则清单”（3–12 条），并要求用户回复 `CONFIRM` 后再落盘。
-     4) 用户确认后，**仅更新** BEGIN/END 段内内容（合并去重；写成可检查条款：目录白名单/必须验证命令/禁止项/产物要求）。
-     5) 输出必须包含：
-        - 更新了哪些文件（路径）
-        - 回滚方式（恢复备份文件）
-        - 下一步建议：`aiws validate .`
-<!-- AIWS_MANAGED_END:opencode:ws-rule -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-spec-review.md

@@ -1,30 +0,0 @@
----
-description: 规范审查：requirements / plan / evidence / gate 完整性
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-spec-review -->
-# ws spec review
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-目标：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
-
-步骤（建议）：
-1) 先运行 `/ws-preflight`。
-   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
-   - requirements / gate / evidence 审查优先 `@oracle`；规范与文档真值补充优先 `@librarian`。
-2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
-   - 当前改动是否能归因到 `Req_ID` / `Problem_ID`
-   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否保持一致
-   - 是否存在越界改动、危险操作或缺失 gate
-3) 将结论落盘到：
-   - 默认：`changes/<change-id>/review/spec-review.md`
-   - 回退：`.agentdocs/tmp/review/spec-review.md`
-4) 输出：
-   - `证据（Evidence）:`
-   - `阻断项（Blockers）:`
-   - `警告（Warnings）:`
-   - `下一步（Next）:`
-5) 若 oMo 不可用：回退为当前 agent 本地 spec review。
-<!-- AIWS_MANAGED_END:opencode:ws-spec-review -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-submodule-setup.md

@@ -1,18 +0,0 @@
----
-description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch）
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-submodule-setup -->
-# ws submodule setup
-
-Thin CLI wrapper. Delegates to `aiws submodule-setup`.
-
-```bash
-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
-```
-<!-- AIWS_MANAGED_END:opencode:ws-submodule-setup -->

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

@@ -1,18 +0,0 @@
----
-description: 完成前验证：finish / handoff 前检查双审查与 validate/evidence
----
-<!-- AIWS_MANAGED_BEGIN:opencode:ws-verify-before-complete -->
-# ws verify before complete
-
-Thin CLI wrapper. Delegates to `aiws verify-bc`.
-
-```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
-```
-<!-- AIWS_MANAGED_END:opencode:ws-verify-before-complete -->

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

@@ -1,18 +0,0 @@
----
-name: ws-handoff
-description: Thin wrapper for `aiws handoff`
----
-
-# ws-handoff
-
-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 handoff
-elif command -v aiws >/dev/null 2>&1; then
-  aiws handoff
-else
-  npx @aipper/aiws handoff
-fi
-```

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

@@ -1,80 +0,0 @@
----
-name: ws-intake
-description: 使用时机：新需求需要逐条澄清、冻结问题时。触发词：需求澄清、intake、冻结问题、前期沟通。注意：需求已冻结直接进 ws-plan。
----
-
-## 配置
-
-| 配置项 | 类型 | 默认值 | 说明 |
-|---|---|---|---|
-| `recommendAnswers` | boolean | true | 提问时先给出推荐答案 |
-| `adversarial` | boolean | true | 对抗式审问：挑战假设+代码库探查 |
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-目标：
-- 在 `/ws-plan` 前把新需求或中大型变更里的待确认问题逐条澄清并冻结。
-- "一题一线程"：每次只处理 1 个问题，允许多轮往返到形成明确结论。
-- 产出轻量草案：`plan/<timestamp>-<slug>.intake.md`。
-
-## Deep Interview 层（前置探询）
-
-在逐题澄清前收集高维信息：
-
-1. **Why 探询**：问"为什么要做？不做有什么后果？"——理解动机，量化 urgency
-2. **非目标（Non-goals）**：显式记录什么不在本次范围内，防止 scope creep
-3. **影响面**：识别影响谁（终端用户、其他模块/系统、其他团队）
-4. **假设显式化**：列出隐含假设，请用户逐条确认
-5. **替代方案**：问"是否考虑过其他方案？为什么选当前这个？"
-6. **约束挑战**：区分硬约束（不可变）和自设约束（可协商）
-7. **优先级**：Must-have / Should-have / Nice-to-have
-8. **成功度量**：量化指标（DAU、转化率、响应时间等）；无法量化则记入风险
-9. **风险预判**：识别 3-5 个最关键风险
-
-输出：以上 9 项归入 intake 草案的 `Deep Interview` 小节。
-
-## 发散-收敛两子阶段
-
-当需求模糊、方向不明确时：
-
-### 发散阶段（Explore）
-- 快速探索 2-3 个方向（≤3 轮），输出每个方向的摘要+风险+依赖
-- **探码前问**：先用 `explore` agent 探查代码库（配置文件、已有实现、文档、测试），探查到的信息直接作为输入，不再重复确认
-
-### 收敛阶段（Converge）
-- 从发散结果选 1 个方向，逐条冻结问题
-- 回到标准"一题一线程"模式
-
-触发条件：用户说"不确定"/"多个方向"等模糊表达。非模糊需求直接进入收敛。
-
-## 核心原则：一次一个问题
-
-- 每轮只推进 1 个 `Open Questions`，未标记 `frozen/deferred` 前不进入下一题
-- 输出格式：`Current question → Why it matters → Options → Exit condition`
-- 用户选择后立即写盘更新草案
-
-**队列保护**：用户一次提出多个问题时建队处理：`Queue: [Q1, Q2, Q3]` / `Current: Q1` / `Status: [open/in_discussion/frozen/deferred]`
-
-执行要求：
-1) 先读真值文件，必要时 `/ws-preflight`
-2) 若存在 `plan/*.intake.md` 则续写，否则新建
-3) 拆解为 `Open Questions`，状态只允许 `open/in_discussion/frozen/deferred`
-4) **对抗式探码后问**：提问前 spawn `explore` agent：
-   - 事实探查：代码库已有答案则记录并跳过提问（`codebase: answered/partial` vs `user: required`）
-   - 矛盾检索：搜代码库中与用户假设矛盾的模式
-   - 边缘案例：空值、并发写入、依赖不可用等
-5) 每次只推进 1 个问题，显式输出 `Current question` / `Why it matters` / `Options` / `Recommended answer` / `Exit condition`
-6) **决策树分支遍历**：问题组织为树，每个答案可能产生子分支。使用缩进树格式追踪：
-   ```
-   ├─ Q1 (frozen)
-   │  ├─ Q1.1 (frozen)
-   │  └─ Q1.2 ← current
-   ├─ Q2 (pending)
-   ```
-   所有叶节点均 `frozen/deferred` 时 intake 完成。无法继续的分支标记 `UNRESOLVED_BRANCH`。
-7) 每轮写盘 intake 草案，至少包含：Deep Interview / Context / Codebase Knowns / Open Questions / Resolved Questions / Frozen Decisions / Draft Scope / Draft Verify / Ready for ws-plan
-8) **Error States**：覆盖已知失败模式（网络超时、数据一致性、输入校验边界），含回滚条件与方式
-9) **Rollback Plan**：涉及数据迁移、API 契约变更、配置漂移修复时，须包含触发条件、回滚步骤、验证方式、副作用
-10) 关键问题已冻结 → `Next: /ws-plan`；否则继续 `/ws-intake`
-
-> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`