@andyqiu/codeforge 0.3.12 → 0.3.14

package/skills/success-criteria/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: success-criteria
+description: 验收标准生成；把 user story + example mapping 输出转为 SMART 验收清单
+metadata:
+  owner: codeforge
+  group: discover
+version: 1.0.0
+allowed_tools: [read]
+mode: on-demand
+trigger: discover Phase E PRD 生成前
+---
+
+# Success Criteria
+
+## SMART 检查表
+
+把每条验收标准逐项对照以下 5 项，不满足的必须改写：
+
+| 维度 | 含义 | 检验问法 |
+|---|---|---|
+| **S — Specific（具体）** | 描述的是一个明确的、可操作的行为或状态，不含模糊副词 | "把'更快'改成'≤ 3 秒'；把'用户满意'改成'NPS ≥ 40'" |
+| **M — Measurable（可测量）** | 有数字或可观测的状态变化，能用工具/日志/截图验证 | "能不能写一段 e2e 测试 / 监控报警来验证这条？" |
+| **A — Achievable（可达到）** | 在当前技术和时间约束下实际可实现，不是理想态 | "这个指标现在的 baseline 是多少？从哪到哪？" |
+| **R — Relevant（相关性）** | 直接关联用户 Job 或业务目标，不是技术指标的自嗨 | "这条验收通过了，用户的原始问题有没有被解决？" |
+| **T — Time-bound（时间窗口）** | 有明确的时间范围或触发时机（何时测、多久内、在哪个版本） | "是'上线后 3 天内'还是'每次操作时'？" |
+
+---
+
+## 验收语法
+
+推荐使用 EARS 句式（本项目已有 `ears-zh` skill 提供模板）将验收条件结构化：
+
+**核心句式**（快速参考）：
+- 事件触发型：`当 <事件> 时，系统应当 <响应>，在 <时间窗口> 内`
+- 状态型：`处于 <状态> 时，系统应当 <持续行为>`
+- 条件型：`如果 <前置条件>，当 <事件> 时，系统应当 <响应>`
+
+**与 Example Mapping 结合**：每张蓝卡（示例）对应一条验收标准；红卡（未解决问题）对应 `open_issues`，不进验收清单。
+
+---
+
+## 反模式（5 种不可验收写法）
+
+以下写法**不允许**出现在验收标准中，发现立即要求用户改写：
+
+| 反模式 | 示例 | 改写方向 |
+|---|---|---|
+| **主观感受** | "用户体验更好" / "界面更美观" / "用起来更流畅" | 改为可观测行为："用户完成任务的步骤数从 7 步减到 4 步" |
+| **没有时间窗** | "系统应该快速响应" / "页面应该快速加载" | 补时间："p95 响应时间 ≤ 500ms" |
+| **双重否定** | "不会出现用户无法完成操作的情况" | 改为正向陈述："用户点击提交后，100% 收到明确的成功或失败反馈" |
+| **技术实现** | "使用 Redis 缓存热点数据" | 改为行为结果："缓存命中率 ≥ 90%，冷启动后 ≤ 5 秒恢复响应" |
+| **加法式兜底** | "还有其他任何用户可能需要的功能" / "以及其他情况" | 删除，或明确列出具体场景 |
+
+---
+
+## 输出格式（写入 handoff.yaml）
+
+每条验收标准输出为以下结构：
+
+```yaml
+acceptance_criteria:
+  - id: "AC-R1-1"
+    description: "新人首次登录 3 秒内看到 ≥5 张推荐卡片"
+    measurable: true
+    metric: "p95_first_paint_ms < 3000 AND card_count >= 5"
+  - id: "AC-R1-2"
+    description: "当月无交易的客户不生成 PDF 文件"
+    measurable: true
+    metric: "导出任务完成后，空客户目录下文件数 = 0"
+```
+
+**id 命名规范**：`AC-<需求id>-<序号>`，如 `AC-R1-1`、`AC-R2-3`。
+
+---
+
+## Phase E 前的快速校验步骤
+
+进入 Phase E 出 PRD 草稿前，逐条过一遍：
+
+1. 收集所有 Phase B/D 中已确认的蓝卡（示例）
+2. 每张蓝卡转一条验收标准（套 EARS 句式）
+3. 逐项过 SMART 5 维，标注不满足的维度
+4. 不满足的条目退回给用户补充，或由 discover 建议改写方案
+5. 全部通过后，写入 `handoff.yaml::acceptance_criteria`

package/skills/weighted-dimensions/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: weighted-dimensions
+description: 5 维加权打分逻辑；输出 weighted_score ∈ [0,1]，供退出条件判断
+metadata:
+  owner: codeforge
+  group: discover
+version: 1.0.0
+allowed_tools: [read]
+mode: on-demand
+trigger: 每轮对话结束前 / Phase 跳转判定
+---
+
+# Weighted Dimensions
+
+## 5 个维度定义
+
+| 维度 | 含义 | 典型证据 |
+|---|---|---|
+| **Functional** | 功能目标是否清晰：做什么、输出什么、核心流程是否可描述 | 用户能用一句话说出"给谁解决什么 Job" |
+| **UX** | 用户体验诉求：交互形式、感知质量、用户旅程中的关键时刻 | 用户提到了"快"/"简单"/"不要让我多点"等具体体验锚点 |
+| **Technical** | 技术可行性边界：性能要求、技术栈约束、已知依赖或限制 | 提及响应时间、系统限制、第三方 API、数据量级等 |
+| **Constraints** | 业务约束：时间窗口、合规、资源限制、显式排除项 | 提及"本期只做……"/"不做……"/"必须兼容……" |
+| **Edge Cases** | 边界场景：异常路径、零状态、错误处理、极端用户行为 | 用户或 discover 主动列举了"如果……怎么处理" |
+
+---
+
+## 加权公式
+
+**默认权重分配**：
+
+| 维度 | 权重 |
+|---|---|
+| Functional | **30%** |
+| UX | **25%** |
+| Technical | **20%** |
+| Constraints | **15%** |
+| Edge Cases | **10%** |
+
+**计算公式**：
+
+```
+weighted_score = Σ (维度得分 × 权重)
+              = F×0.30 + U×0.25 + T×0.20 + C×0.15 + E×0.10
+```
+
+其中每个维度得分 ∈ [0, 1.0]（0 = 完全未知，0.5 = 部分清晰，1.0 = 充分明确）。
+
+**示例**：
+
+```
+F=0.8, U=0.5, T=0.3, C=0.6, E=0.2
+weighted_score = 0.8×0.30 + 0.5×0.25 + 0.3×0.20 + 0.6×0.15 + 0.2×0.10
+              = 0.24 + 0.13 + 0.06 + 0.09 + 0.02
+              = 0.54
+```
+
+---
+
+## 阈值表
+
+| 阶段跳转 | 所需 weighted_score | 备注 |
+|---|---|---|
+| Phase A → B | **≥ 0.5** | 且 Functional ≥ 0.7，用户能说出核心 Job |
+| Phase B → C | **≥ 0.65** | ≥ 3 个具体场景已确认 |
+| Phase C → D | —（由 challenger 红旗处理状态决定） | 至少 1 轮 challenger 反对被用户正面回应 |
+| Phase D → E | **≥ 0.8** | 或 0.6-0.8 且用户明确说"够了" |
+
+---
+
+## 评分表输出模板
+
+当用户触发「评估 / 打分 / 评分 / 严谨模式 / 看进度 / 澄清度 / 现在多少分 / score / rate」关键词时，或进入 Phase E 前，按此格式输出：
+
+```
+─────────────────────────────────────
+本轮澄清度评分（满分 1.0）：
+| 维度          | 权重 | 当前 | 加权 |
+|---------------|------|------|------|
+| Functional    | 30%  | 0.8  | 0.24 |
+| UX            | 25%  | 0.5  | 0.13 |
+| Technical     | 20%  | 0.3  | 0.06 |
+| Constraints   | 15%  | 0.6  | 0.09 |
+| Edge Cases    | 10%  | 0.2  | 0.02 |
+| **总分**      |      |      | 0.54 |
+
+档位：Insufficient (<0.6) → 继续澄清
+建议下一步：聚焦 Technical 维度（本轮最低分）
+─────────────────────────────────────
+```
+
+**档位规则**：
+
+- **≥ 0.8** → Sufficient，建议进 Phase E 产出 PRD
+- **0.6 ~ 0.8** → Acceptable，可选退出（用户拍板）
+- **< 0.6** → Insufficient，必须继续澄清
+
+---
+
+## 维度打分指南
+
+**Functional 常见打分依据**：
+- 0.0：只说了"做个东西"，完全不知道做什么
+- 0.2：有隐约方向但目标群体/核心输出不明（如"做个管理工具"）
+- 0.4：目标群体 + 核心使用场景已清晰，但核心功能边界还未明确（如"给老板看指标的看板"，知道谁用/做什么，但不知道哪些指标/什么展示形式）
+- 0.5：知道大方向（"做个导出"），但不知道输出形式、流程
+- 1.0：输入输出明确，核心流程可描述，用户能说出 Job
+
+> **初轮信息密度校准**（方案 A 补充）：Phase A 初轮评分反映的是**信息密度**，不是需求质量高低。
+> 用户首轮说出「目标群体 + 核心 Job」即可给 0.4，不要因为细节不足降到 0.2。
+> 0.2 应保留给真正「只有一个动词、连做什么都不清楚」的极端情形。
+> 典型校准案例：「做看板让老板看指标」= 目标群体（老板）+ 核心输出（看板/指标）已给出 → Functional ≥ 0.4。
+
+**Edge Cases 常见打分依据**：
+- 0.0：完全没讨论过边界
+- 0.5：讨论了 1-2 个正常 happy path，无异常路径
+- 1.0：覆盖了至少 3 个边界场景（空状态/错误/极端输入）

package/workflows/discover-flow.yaml

@@ -0,0 +1,150 @@
+# ──────────────────────────────────────────────────────────────
+# discover-flow.yaml — Discover Agent 5 阶段需求澄清流程
+# trigger: /discover
+# 流程：phase-a 入口门控 → phase-b JTBD 挖掘 → phase-c 对抗审查
+#       → phase-d 假设暴露 + 补边界 → phase-e PRD + handoff 生成
+#
+# ⚠️ Schema 适配说明（reviewer REQUEST_CHANGES 修复 1，选项 A）：
+#    lib/workflow-loader.ts 的 WorkflowSchema.strict() 只接受
+#    name / description / version / trigger / context_template /
+#    max_loops / steps 这些顶层字段；StepSchema.strict() 只接受
+#    name / agent / description / inject_context / requires_human_approval /
+#    actions / on_error / max_retries / timeout / auto_feedback /
+#    on_decision —— 不允许 id / skills / exit_when / on_success /
+#    on_fail / artifacts。
+#
+#    Session 3 原始设计中那些"声明字段"的语义（每阶段允许调哪些
+#    skill、退出条件、产物路径）按 ADR-discover-phase1 D4 决策属于
+#    **声明 ≠ 调用**：workflow runner 不解析、不强制，由 discover
+#    agent 在对话中通过 opencode `skill` 工具按需执行。因此本次修复
+#    把这些信息全部下沉到每个 step 的 `description:` 文本块中作为
+#    可审计的契约声明，loader 把它当普通字符串处理，不影响 schema
+#    校验，"声明仍是 source of truth"。
+# ──────────────────────────────────────────────────────────────
+
+name: discover-flow
+version: 1.0.0
+description: |
+  双 agent（discover + discover-challenger）协作的 5 阶段需求澄清流程：
+    phase-a 入口门控   → 判断用户输入是否清晰到可进入挖掘
+    phase-b JTBD 挖掘  → 澄清 job-to-be-done + 核心 user story
+    phase-c 对抗审查   → 召唤 challenger 子 agent 做反 sycophancy 强对抗
+    phase-d 假设暴露   → 处理红旗 + Example Mapping 补 case
+    phase-e PRD+handoff → 输出 PRD.md + handoff.yaml
+  本 workflow 不直接调用 skill，由 discover agent 按 ## Skill 路由表 决定。
+
+trigger: /discover
+max_loops: 5
+
+steps:
+  - name: phase-a 入口模糊度门控
+    agent: discover
+    description: |
+      [阶段 A] 入口门控
+      ─────────────────────────────────────
+      职责：首次接到用户输入，判断 5 维度清晰度（who/what/why/scope/criteria）；
+            模糊则要求用户补充，清晰则进入 phase-b。
+
+      允许调用 skill（声明，由 agent 按需触发，runner 不强制）：
+        - ambiguity-gate
+        - weighted-dimensions
+
+      退出条件（声明，由 agent 自检；不通过则在本 step 继续澄清）：
+        - weighted_score >= 0.5
+        - user_intent 字段已确立
+
+      成功后跳转：phase-b
+      失败回退：留在本 step 继续追问
+
+      产物（可选）：
+        - handoff.draft.yaml（草稿，本阶段非必需）
+
+  - name: phase-b JTBD 挖掘
+    agent: discover
+    description: |
+      [阶段 B] JTBD 挖掘
+      ─────────────────────────────────────
+      职责：澄清 job-to-be-done + 核心 user story；中段调用 example-mapping
+            挖 BDD 场景；每轮末调用 weighted-dimensions 更新加权分。
+
+      允许调用 skill（声明）：
+        - weighted-dimensions
+        - example-mapping
+
+      退出条件（声明）：
+        - weighted_score >= 0.65
+        - core_user_story 字段已确立
+
+      成功后跳转：phase-c
+      失败回退：留在本 step 继续澄清
+
+      产物（必须）：
+        - handoff.draft.yaml
+
+  - name: phase-c 对抗审查
+    agent: discover
+    description: |
+      [阶段 C] 对抗审查
+      ─────────────────────────────────────
+      职责：召唤 discover-challenger 子 agent 前，调用 devils-advocate 准备
+            4 种 combo（A/B/C/D）对抗框架；challenger 返回红旗判定
+            （YES/NO）后由 discover 决定下一步。
+
+      允许调用 skill（声明）：
+        - devils-advocate
+        - weighted-dimensions
+
+      退出条件（声明）：
+        - red_flags_handled == true（challenger 报告中的红旗已全部回应）
+
+      成功后跳转：phase-d
+      失败回退：留在本 step 继续处理红旗
+
+      产物（必须）：
+        - handoff.draft.yaml（更新红旗处理记录）
+
+  - name: phase-d 假设暴露与补边界
+    agent: discover
+    description: |
+      [阶段 D] 假设暴露 + 补边界
+      ─────────────────────────────────────
+      职责：处理 challenger 报告中的红旗 + 漏洞；末段调用 example-mapping
+            补充边界 case；Question 卡 ≤ 2 张时收敛进入 phase-e。
+
+      允许调用 skill（声明）：
+        - example-mapping
+        - weighted-dimensions
+
+      退出条件（声明）：
+        - red_flags == [] （或全部已处理）
+        - weighted_score >= 0.75
+
+      成功后跳转：phase-e
+      失败回退：留在本 step 继续补边界
+
+      产物（必须）：
+        - handoff.draft.yaml（更新边界 case）
+
+  - name: phase-e PRD 与 handoff 生成
+    agent: discover
+    description: |
+      [阶段 E] PRD + handoff 生成
+      ─────────────────────────────────────
+      职责：调用 success-criteria 把 user story + example mapping 转成 SMART
+            验收清单；调用 ears-zh 把验收套 EARS 中文句式；最终产出
+            PRD.md + handoff.yaml。
+
+      允许调用 skill（声明）：
+        - success-criteria
+        - ears-zh
+
+      退出条件（声明）：
+        - handoff_yaml_complete == true
+        - weighted_score >= 0.8
+
+      成功后跳转：__end__（workflow 结束）
+      失败回退：留在本 step 继续完善 PRD
+
+      产物（必须）：
+        - PRD.md
+        - handoff.yaml