@boyingliu01/xp-gate 0.7.0 → 0.8.0

package/skills/delphi-review/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: delphi-review
-description: "Delphi consensus review: multi-round anonymous expert review until unanimous APPROVAL. Supports design/code-walkthrough modes. 2-3 experts from different providers. MANDATORY before implementation, design, or architecture decisions. Trigger: 'review this design', '评审这个需求', 'design review', '多专家评审', 'consensus review', 'code walkthrough', 'push review', or any request for multi-expert review of requirements, design docs, architecture, or PRs."
+description: "Use when asked to review a design, plan, or architecture; before implementation starts; or when multi-expert consensus is needed. Triggers: 'review this design', '评审这个需求', 'design review', '多专家评审', 'consensus review', 'code walkthrough', 'push review', 'architecture review', 'PR review', or any request for multi-expert evaluation of requirements, design docs, or PRs."
 ---
 
 # Delphi Consensus Review
 
+## Scope
+
+**In Scope:**
+- Multi-round anonymous expert consensus review (design + code-walkthrough modes)
+- 2-3 experts from different providers with statistical consensus (>= 91%)
+- Structured verdict: APPROVED / PASS_WITH_CAVEATS / REQUEST_CHANGES
+- Domestic models only (no Anthropic/OpenAI/Google)
+
+**Out of Scope:**
+- Does NOT implement code changes (review only, implementation is separate)
+- Does NOT replace testing or CI/CD verification
+- Does NOT handle deployment or release decisions
+
 ## 核心原则
 
 **Delphi 方法只有一个目的：得到所有专家一致认可的可行方案。**
@@ -14,7 +27,7 @@ description: "Delphi consensus review: multi-round anonymous expert review until
 1. **匿名性** — Round 1 专家互不知道对方意见
 2. **迭代** — 多轮直到共识，不是固定轮数
 3. **受控反馈** — 每轮看到其他专家意见
-4. **统计共识** — >=95% 一致才算共识
+4. **统计共识** — >=91% 一致才算共识
 
 ### 质量优先
 
@@ -82,24 +95,24 @@ description: "Delphi consensus review: multi-round anonymous expert review until
 
 | 阈值 | 说明 |
 |------|------|
-| **>=95%** | 推荐默认 |
+| **>=91%** | 推荐默认 |
 | 100% | 完全一致（更严格） |
 
 ---
 
-## 完整流程
+## Delphi 评审执行过程
 
 ```
 Phase 0: 准备 → Round 1: 匿名独立评审 → 共识检查
     │
-    ├─ 一致 + >=95% + APPROVED → ✅ 完成
+    ├─ 一致 + >=91% + APPROVED → ✅ 完成
     │
-    └─ 不一致 或 <95% 或 REQUEST_CHANGES
+    └─ 不一致 或 <91% 或 REQUEST_CHANGES
           │
           ▼
        Round 2: 交换意见 → 共识检查
           │
-          ├─ 一致 + >=95% + APPROVED → ✅ 完成
+          ├─ 一致 + >=91% + APPROVED → ✅ 完成
           │
           └─ 仍分歧 或 REQUEST_CHANGES
                 │
@@ -202,14 +215,96 @@ Phase 0: 准备 → Round 1: 匿名独立评审 → 共识检查
 
 ---
 
+## Triggers
+
+This skill activates on any request for multi-expert review. Common triggers:
+
+**English:**
+- "review this design"
+- "design review"
+- "architecture review"
+- "consensus review"
+- "code walkthrough"
+- "push review"
+- "multi-expert review"
+- "PR review"
+
+**Chinese:**
+- "评审这个需求"
+- "多专家评审"
+- "设计评审"
+- "架构评审"
+- "代码走查"
+
+**Related commands:**
+- `/delphi-review` - Design review mode
+- `/delphi-review --mode code-walkthrough` - Pre-push code walkthrough
+
+---
+
+## Workflow Steps
+
+1. **Determine mode** - Design review (default) or code-walkthrough (--mode code-walkthrough)
+2. **Dispatch anonymous experts** - 2-3 experts from ≥2 different domestic model providers
+3. **Collect Round 1 independent reviews** - Anonymous, no cross-expert bias
+4. **Synthesize feedback** - Measure consensus, identify disagreements
+5. **Run Round 2+ until consensus** - Exchange opinions, iterate until ≥91% agreement
+6. **Block on unresolved Critical/Major** - Zero-tolerance: all Critical/Major must be resolved
+7. **Emit verdict** - APPROVED (with specification.yaml) or REQUEST_CHANGES (fix + re-review)
+
+**Consensus threshold:** ≥91% (project standard for Delphi review approval)
+**Model policy:** Domestic models only (DeepSeek, Qwen, Kimi, GLM, MiniMax). Foreign models (Anthropic/OpenAI/Google) forbidden.
+
+---
+
+## Scope
+
+**IN Scope:**
+- Design document review (requirements, architecture, PRDs)
+- Pre-implementation planning review
+- Code walkthrough (git push validation, max 20 files/500 LOC)
+- Multi-expert consensus building
+- Specification extraction (design → specification.yaml)
+
+**OUT Scope:**
+- Single-expert review (use `/review` instead)
+- Post-implementation review (use `/requesting-code-review`)
+- Security audit (use `/security-research` or `/cso`)
+- Performance benchmarking (use `/benchmark`)
+
+---
+
+## Examples
+
+**Example 1: Design review**
+```bash
+/delphi-review
+```
+→ 3 experts review design doc → consensus report + specification.yaml
+
+**Example 2: Code walkthrough**
+```bash
+/delphi-review --mode code-walkthrough
+```
+→ Pre-push validation → .code-walkthrough-result.json
+
+**Example 3: Chinese trigger**
+```
+User: 评审这个需求文档
+→ Auto-detects delphi-review trigger → dispatches experts
+```
+
+---
+
 ## Output Format (MANDATORY)
-Every review round output MUST follow this exact JSON structure:
+
+Every review round output MUST follow this exact JSON structure for design mode:
 
 ```json
 {
   "expert_id": "A|B|C",
   "round": 1,
-  "mode": "design|code-walkthrough",
+  "mode": "design",
   "verdict": "APPROVED|REQUEST_CHANGES|REJECTED",
   "confidence": 9,
   "critical_issues": ["..."],
@@ -218,11 +313,14 @@ Every review round output MUST follow this exact JSON structure:
   "consensus_report": {
     "agreed_items": ["..."],
     "disagreed_items": ["..."],
-    "final_verdict": "APPROVED|REQUEST_CHANGES"
+    "final_verdict": "APPROVED|REQUEST_CHANGES",
+    "consensus_ratio": 0.95
   }
 }
 ```
 
+**For code-walkthrough mode**, output follows `.code-walkthrough-result.json` schema (see `references/code-walkthrough.md`).
+
 **Anti-patterns mapping to assertions:**
 - `Round 1 → 生成报告 → "评审完成"` → Output MUST NOT have `verdict: APPROVED` if `critical_issues` exist.
 - `只处理 Critical，忽略 Major` → Output MUST include `major_concerns` array, even if empty.
@@ -242,7 +340,7 @@ Every review round output MUST follow this exact JSON structure:
 - [ ] Round 2+ 完成（交换意见 / 最终立场）
 
 **CRITICAL — 共识验证:**
-- [ ] 问题共识比例 >=95%
+- [ ] 问题共识比例 >=91%
 - [ ] 所有 Critical Issues 已解决
 - [ ] 所有 Major Concerns 已处理
 
@@ -316,54 +414,6 @@ Every review round output MUST follow this exact JSON structure:
 
 ---
 
-## Qoder 平台适配
-
-在 Qoder IDE 中，delphi-review 的多专家评审通过以下方式实现：
-
-### 多模型评审（替代 OpenCode 的多 agent 配置）
-
-利用 Qoder 的多模型访问能力（类似 coding plan），通过 Agent subagent 派发不同模型完成 Expert A/B/C 评审：
-
-| 专家 | 角色 | Qoder Subagent 映射 | 说明 |
-|------|------|---------------------|------|
-| Expert A (架构) | 架构审查 | **plan-agent** subagent | 适合架构级分析 |
-| Expert B (技术) | 实现审查 | **CodeReview** subagent | 代码审查天然适合 |
-| Expert C (可行性) | 可行性仲裁 | **plan-agent** subagent（不同 prompt） | 与 Expert A 使用不同的评审 prompt |
-
-**执行流程**：
-1. orchestrator 准备评审材料（设计文档/代码变更）
-2. 分别派发 2-3 个 Agent subagent，每个 subagent 携带对应专家的 system prompt
-3. 收集各专家评审结果 → 合并为共识报告
-4. 如未达成共识 → 迭代（携带其他专家意见重新评审）
-
-### 专家配置
-
-专家→模型映射通过 `.qoder/delphi-config.json` 配置：
-
-```json
-{
-  "experts": {
-    "A": { "role": "architecture", "model_hint": "deepseek-v4-pro" },
-    "B": { "role": "implementation", "model_hint": "kimi-k2.6" },
-    "C": { "role": "feasibility", "model_hint": "qwen3.6-plus" }
-  },
-  "consensus_threshold": 0.95,
-  "max_rounds": 5
-}
-```
-
-> **注意**：`model_hint` 是建议模型，实际使用的模型取决于 Qoder 的模型调度策略。
-
-### 降级方案
-
-如果多模型 subagent 调用不可用，降级为**单模型多角色模式**：
-- 同一模型分别扮演 Expert A/B/C（不同 system prompt）
-- 明确标注降级警告：`[DEGRADED] 单模型多角色模式，失去跨 provider 匿名性保护`
-
-详细配置和执行指南参见 `references/qoder-multi-model.md`。
-
----
-
 ## Anti-Patterns
 
 | ❌ 错误 | ✅ 正确 |
@@ -372,7 +422,7 @@ Every review round output MUST follow this exact JSON structure:
 | 只处理 Critical，忽略 Major | 零容忍：Critical/Major 全部必须处理，不可跳过或降级 |
 | 单专家自评 | 至少 2 位不同 provider 的专家 |
 | 用户说"时间紧急"就跳过 | 评审是投资不是开销，跳过后期返工成本更高 |
-| "专家几乎一致"就通过 | "几乎" = 不一致，继续到 >=95% |
+| "专家几乎一致"就通过 | "几乎" = 不一致，继续到 >=91% |
 | 使用 Anthropic/GPT/Gemini 等国外昂贵模型 | 必须使用国产开源模型（DeepSeek, Qwen, Kimi, GLM, MiniMax） |
 | 三个专家使用同一厂家模型 | 必须来自至少 2 家不同厂家 |
 
@@ -387,7 +437,7 @@ Every review round output MUST follow this exact JSON structure:
 | "这只是小变更" | 所有变更都需要评审 |
 | "Round 1 就够了" | 不够，必须多轮直到共识 |
 | "生成报告就完成了" | APPROVED 才算完成 |
-| "2/3 同意就是共识" | 还要检查问题共识比例 >=95% |
+| "2/3 同意就是共识" | 还要检查问题共识比例 >=91% |
 
 ---
 
@@ -395,25 +445,10 @@ Every review round output MUST follow this exact JSON structure:
 
 **Delphi 评审完成的唯一标准：**
 1. ✅ 所有专家裁决 APPROVED
-2. ✅ 问题共识 >=95%
+2. ✅ 问题共识 >=91%
 3. ✅ 所有 Critical Issues 已修复验证
 4. ✅ 所有 Major Concerns 已处理
 5. ✅ 共识报告已生成
 6. ✅ 用户已确认
 
 **缺少任何一项 = 未完成**
-## Output Format (MANDATORY)
-Every delphi review round MUST output valid JSON:
-```json
-{
-  "skill_name": "delphi-review",
-  "mode": "design|code-walkthrough",
-  "phase": "Round 1|Round 2|Round 3|Consensus",
-  "expert_id": "A|B|C",
-  "verdict": "APPROVED|REQUEST_CHANGES|REJECTED",
-  "confidence": 8,
-  "issues": [{"id": "string", "severity": "critical|major|minor", "description": "string"}],
-  "consensus_report": {"status": "pending|consensus|disagreement"}
-}
-```
-**Eval assertions check for:** `verdict` enum values, `confidence` range, `issues` structure, `consensus_report.status`.

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in a codebase, informed by domain language in CONTEXT.md and decisions in ADRs. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable. Run periodically (weekly or after surges of development).
+---
+
+# Improve Codebase Architecture
+
+周期性架构健康检查：发现 **shallow module → deep module** 的深度化机会。目标是提升可测试性、AI 可导航性、模块边界清晰度。
+
+与 XP-Gate 质量门禁的分工：
+| 机制 | 时机 | 作用 |
+|------|------|------|
+| **6 道门禁** | 每次 commit | 被动拦截明显问题（函数过长、重复代码等） |
+| **improve-codebase-architecture** | 每周/开发潮后 | 主动深度化改进（seam 识别、模块合并、接口提炼） |
+
+---
+
+## 术语（与 XP-Gate Principles 一致）
+
+| 术语 | 定义 |
+|------|------|
+| **Module** | 任何有接口和实现的东西（函数、类、包、slice） |
+| **Interface** | 调用者使用前必须知道的一切：类型、不变量、错误模式、顺序、配置 |
+| **Implementation** | 接口背后的代码 |
+| **Depth** | 接口的杠杆率：大量行为隐藏在简单接口后。**Deep = 高杠杆**。**Shallow = 接口几乎与实现一样复杂** |
+| **Seam** | 接口所在位置；可以在不修改实现的情况下改变行为的地方 |
+| **Adapter** | 在 seam 处满足接口的具体实现 |
+| **Locality** | 深度带来的可维护性收益：变更、bug、知识集中在一处 |
+
+---
+
+## 核心判断工具
+
+### Deletion Test
+想象删除某个模块：
+- 如果复杂性消失 → 它是 pass-through，不值得保留
+- 如果复杂性在 N 个调用方中重新出现 → **它真正提供了价值**
+- **"Yes, concentrates" = 你想发现的信号**
+
+### The Interface Is the Test Surface
+接口就是测试的边界。如果测试需要深入实现细节，说明接口太浅。
+
+### One Adapter = Hypothetical Seam. Two Adapters = Real Seam.
+只有一个实现满足接口 → 可能过度抽象。两个以上 → 真正的可替换边界。
+
+---
+
+## 流程
+
+### 1. 探索
+
+先读项目的 `CONTEXT.md`（领域语言）和 `docs/adr/`（架构决策）。
+
+然后有机地走查代码库（不要遵循死板启发式），注意你在哪里感受到摩擦：
+
+- 理解一个概念是否需要在多个小文件间跳来跳去？
+- 模块是否 **shallow** — 接口几乎与实现一样复杂？
+- 纯函数是否仅仅为了可测试性而被提取，但真正的 bug 隐藏在调用方式中？（缺乏 **locality**）
+- 紧密耦合的模块是否在其 seams 之处泄漏？
+- 哪些部分难以通过当前接口进行测试？
+
+对任何怀疑 shallow 的模块执行 **Deletion Test**：删除它会让复杂性集中还是分散？"是的，会集中"就是你要的信号。
+
+### 2. 呈现候选项
+
+以编号列表呈现深度化机会。每项包含：
+
+- **Files** — 涉及哪些文件/模块
+- **Problem** — 当前架构为何造成摩擦（使用 CONTEXT.md 中的领域术语）
+- **Solution** — 自然语言描述会怎样改变
+- **Benefits** — 用 locality 和 leverage 解释收益，以及测试会怎样改善
+
+**使用 CONTEXT.md 领域术语。如果与 ADR 冲突**，仅在摩擦值得重新讨论 ADR 时才标注：
+> *"Contradicts ADR-0007 — 但值得重新打开，因为…"*
+
+不要列出 ADR 禁止的每个理论重构。
+
+**此时不要提出接口设计**。先问用户："你想探索哪个候选项？"
+
+### 3. 用户选择候选项
+
+仅当用户明确选择某个候选项时，才进入步骤 4。
+
+### 4. Grilling 循环（设计树遍历）
+
+用户选中某个候选项后，进入 grilling 对话：
+- 遍历约束、依赖、深度化模块的形状
+- seam 背后放什么、什么不放在 seam 背后
+- 哪些测试能在深度化后存活/新增
+
+**对话中的副作用**（决策固化时立即执行）：
+- 命名不在 CONTEXT.md 中的新概念 → **新增到 CONTEXT.md**
+- 模糊术语在对话中变清晰 → **更新 CONTEXT.md**
+- 用户拒绝候选项且有有理由 → **提议记录为 ADR**（避免未来重复建议）
+- 需要探索替代接口 → **按接口设计原则引导**
+
+### 5. 输出（可选）
+
+如果用户在 grilling 后决定执行重构：
+- 生成重构计划（含文件列表、步骤顺序、风险点）
+- 调用 test-driven-development skill 执行重构（保持行为不变）
+
+---
+
+## 与 XP-Gate 集成
+
+### 触发时机
+```
+Phase 5 (FEEDBACK) 后推荐调用：
+  → learn + retro + **improve-codebase-architecture**
+  → 发现架构摩擦 → 记录到 retro → 下一 Sprint 纳入 backlog
+
+或作为独立周期性任务：
+  → /improve-codebase-architecture  → 每周/开发潮后
+```
+
+### 与 ralph-loop 的关系
+架构改进本身可以作为一个独立的 REQ 通过 ralph-loop 执行：
+- REQ: "深度化 Order 模块（从 N 个散文件合并为 deep module）"
+- 通过 test-driven-development 保证行为不变
+
+### 与质量门禁的关系
+架构改进后，质量门禁的 violation 数量应减少：
+- God class → 拆分为 deep modules → SOLID-001 (SRP) 告警消失
+- Deep nesting → 封装为简单接口 → CC-002 告警消失
+- Code duplication → 提取公共 deep module → Gate 2 (Dup Code) 改善
+
+---
+
+## Anti-Patterns
+
+| ❌ 错误 | ✅ 正确 |
+|---------|---------|
+| 仅在文件层面重构（拆分大文件） | 在概念边界处重构（deep module 封装行为） |
+| 为了测试而提取纯函数 | 为了 locality 和组织行为边界而重构 |
+| 过度设计接口（只有一个 adapter） | 发现真实 seam（≥2 adapters 或需要可测试性）后再抽象 |
+| 忽视现有 ADR 提出重构 | 尊重 ADR，仅在摩擦值得重新讨论时标注冲突 |
+| 一次性重构整个模块 | 逐个候选项执行，使用 TDD 保证行为不变 |
+| 与 ADR 冲突但不记录决策 | 记录为 ADR，避免未来重复建议 |
+
+---
+
+## 使用示例
+
+```
+/improve-codebase-architecture
+
+→ Explore: 读取 CONTEXT.md, 走查代码库
+→ 发现 3 个浅模块候选项
+→ 呈现: #1 Order 模块过浅 / #2 Auth 适配器泄漏 / #3 支付领域缺乏 locality
+→ 用户选中 #1
+→ Grilling: 讨论 Order 的 seam 应该在哪
+→ 更新 CONTEXT.md: 新增 "Order Intake" 术语
+→ 提议 ADR: "Order 状态机封装" → 用户同意 → 创建 docs/adr/000X.md
+→ 输出: 重构计划 → TDD 执行
+```

package/skills/ralph-loop/SKILL.md

@@ -1,13 +1,6 @@
 ---
 name: ralph-loop
-description: >
-  Default Phase 2 BUILD mode for Sprint-Flow. Processes ONE REQ at a time from
-  specification.yaml with clean isolated context per subagent dispatch, persists
-  memory via git history + classified learnings, runs full regression tests on each
-  REQ, and only commits on verification pass. Designed to reduce token consumption
-  from linear context accumulation to per-REQ fixed budgets (40-67% savings).
-  Token-constraint is the default — every Phase 2 uses this mode automatically.
-  Use `--mode parallel` to opt into the legacy all-at-once mode if needed.
+description: Use when executing Sprint-Flow Phase 2 BUILD, processing one REQ, building the next requirement, iterating with clean context, or requiring full regression per requirement.
 maturity: stable
 ---
 
@@ -25,6 +18,25 @@ maturity: stable
 | **浓缩型分类学习** | permanent（架构级）+ contextual（最近 3 条）双层 learnings |
 | **AGENTS.md 统一更新** | orchestrator 统一写，subagent 不直接修改 — 无竞态 |
 
+---
+
+## Triggers
+
+**关键词触发**：ralph-loop, process one REQ, build next requirement, Phase 2 BUILD, iterate REQ, isolated REQ build, clean context, full regression
+
+**使用场景**：
+- 执行 Sprint-Flow Phase 2 BUILD 阶段
+- 从 specification.yaml 读取需求逐个实现
+- 需要控制每个 REQ 的 token 预算
+- 防止上下文污染（前一个 REQ 的实现细节影响后一个 REQ）
+- 需要全量回归测试保证不引入回归
+- 需要持久化 learnings 供后续 REQ 参考
+
+**何时不使用**：
+- 需求数量极少（1-2 个）且相互独立，可以并行
+- 紧急热修复，不需要完整 Sprint Flow
+- 明确使用 `--mode parallel` 切换到并行模式
+
 ## 作为 Phase 2 默认行为
 
 Ralph Loop 是 Sprint-Flow **Phase 2 BUILD 的默认模式**：
@@ -297,43 +309,162 @@ Phase 0, 1, 3-6 行为完全不变。
 
 ---
 
-## Qoder 平台适配
+## Workflow Steps (Mandatory Execution Order)
+
+**每个 REQ 必须按以下顺序执行，不得跳过或重排**：
+
+1. **Load next READY REQ**
+   - 从 specification.yaml 读取下一个依赖已满足的 REQ
+   - 检查 priority 和 status (pending 状态)
+   - 构建依赖图，确认无循环依赖
+
+2. **Create isolated context**
+   - 清空前一个 REQ 的对话历史
+   - 注入：当前 REQ + AC + permanent learnings + contextual learnings (最近 3 条)
+   - 注入：AGENTS.md + git log --oneline -5 + 测试基础设施摘要
+
+3. **Dispatch build subagent**
+   - 使用 `task(category="unspecified-high", load_skills=["test-driven-development"], timeout=300)`
+   - 强制 TDD 流程：RED → GREEN → REFACTOR
+   - 强制执行 Mock 边界策略（详见 Mock 边界表）
+
+4. **Run full regression tests**
+   - L1: typecheck + lint on changed files
+   - L1b: 检查测试先行比率 (新增测试行数 / 总新增行数 ≥ 40%)
+   - **L2: 全量测试运行**（不只是 @test 当前 REQ 的测试）
+   - L3: 检查整体覆盖率 ≥ 80%
+
+5. **Fix until green or block**
+   - 失败 → retry (max 3 次，每次注入失败摘要)
+   - 第 3 次仍失败 → BLOCK → 等待用户决策 (skip/manual/stop/rollback)
+   - 通过 → git commit + 标记 done
+
+6. **Persist learnings**
+   - 分类为 permanent（架构级）或 contextual（临时性）
+   - 自动升级条件：被≥2 个 REQ 引用 或 涉及接口/数据结构
+   - 调用 `gstack/learn` 总结经验教训
+
+7. **Update sprint state**
+   - orchestrator 统一更新 AGENTS.md（append `## ralph-loop: [REQ-XXX title]`）
+   - 原子写 checkpoint (progress.log)
+   - 继续下一个 READY REQ
+
+**禁止行为**：
+- ❌ 跳过测试基础设施检查
+- ❌ 只运行部分测试（必须全量回归）
+- ❌ 验证失败仍 commit
+- ❌ 多个 subagent 同时写 AGENTS.md
+- ❌ 修改前一个 REQ 的代码（除非修复回归）
+
+---
+
+## Scope
+
+**In Scope**：
+- Phase 2 BUILD 阶段的 REQ 级迭代构建
+- 从 specification.yaml 读取需求并逐个实现
+- 测试先行（TDD）+ 全量回归测试
+- 持久化 learnings 供后续 REQ 参考
+- 依赖排序和循环依赖检测
+- 崩溃恢复（从 checkpoint 继续）
+
+**Out of Scope**：
+- Phase 0-1 (THINK/PLAN) 的需求分析和设计
+- Phase 3-6 (REVIEW/USER ACCEPT/FEEDBACK/SHIP) 的后续阶段
+- 并行模式（需显式使用 `--mode parallel` 切换到 `dispatching-parallel-agents`）
+- 紧急热修复（应使用标准 sprint-flow 或手动处理）
+- 非 specification.yaml 定义的需求（临时需求应先纳入 spec 再执行）
+
+---
+
+## Examples
+
+**Example 1: 标准 Sprint Flow 启动**
+```bash
+/sprint-flow "开发用户登录功能，支持 JWT 和 OAuth2" --type web-nextjs
+# → Phase 0-1 完成设计评审后，Phase 2 自动进入 ralph-loop 模式
+# → 按拓扑顺序处理 REQ-001 (User Model) → REQ-002 (Auth Middleware) → REQ-003 (Login API)
+```
+
+**Example 2: 单个 REQ 构建**
+```bash
+/ralph-loop
+# → 从 specification.yaml 读取下一个 READY REQ
+# → 创建孤立上下文，dispatch TDD subagent
+# → 全量回归测试通过后 commit
+```
+
+**Example 3: 处理阻塞 REQ**
+```
+REQ-005 失败 3 次 → BLOCKED
+→ 用户决策：
+  - skip: 跳过此 REQ，继续 REQ-006
+  - manual: 手动修复后重新 dispatch
+  - stop: 停止整个 ralph-loop，保留已 done commits
+  - rollback: git reset 回上一个稳定版本
+```
+
+**Example 4: 崩溃恢复**
+```bash
+# 系统崩溃后重新启动
+/ralph-loop --resume
+# → 检测 progress.log → 跳过已 done REQs
+# → 从最后一个 pending REQ 继续，无需重做已完成工作
+```
+
+**Example 5: 测试基础设施缺失**
+```
+REQ-001 开始 → 检查 test-utils.ts → 不存在
+→ dispatch "生成测试基础设施" subagent
+→ retry max 2 次 → 仍失败 → BLOCK 或 fallback inline 生成
+→ 基础设施就绪后继续业务代码开发
+```
+
+---
 
-### Subagent Dispatch（替代 OpenCode 的 `task()` API）
+## Output Contract (Mandatory Checklist)
 
-在 Qoder 环境中，ralph-loop 的 subagent 派发使用以下方式：
+**每个 REQ 完成时必须输出以下结构化检查清单**：
 
-| 原调用 | Qoder 替代 | 说明 |
-|---------|------------|------|
-| `task(category="unspecified-high", load_skills=["test-driven-development"])` | **orchestrator 直接执行** | ralph-loop 逐 REQ 迭代，每个 REQ 在干净上下文中执行，不需要独立 subagent |
-| `gstack/learn` | **Qoder Memory 系统** | permanent learnings → `UpdateMemory`；contextual learnings → 会话上下文 |
+```markdown
+## REQ-XXX: [Title] - Execution Summary
 
-### Learnings 持久化（替代 gstack/learn）
+**Status**: ✅ PASS / ❌ FAIL (retry n/3) / 🚫 BLOCKED
 
-ralph-loop 的 learnings 分类机制在 Qoder 中通过 Memory 系统实现更优雅的持久化：
+**Context Isolation**:
+- [ ] Previous REQ context cleared
+- [ ] Permanent learnings injected (N items)
+- [ ] Contextual learnings injected (≤3 items)
+- [ ] Test infrastructure confirmed ready
 
-| Learnings 类型 | 原方案 | Qoder 替代 |
-|---------------|--------|------------|
-| **permanent** | progress.log + AGENTS.md | `UpdateMemory`（project_introduction / expert_experience / development_practice_specification 类型） |
-| **contextual** | progress.log（最近 3 条） | 当前会话上下文传递，不持久化 |
-| **Sprint retro** | gstack/learn | Phase 5 结束时 `UpdateMemory` 写入 |
+**TDD Compliance**:
+- [ ] Tests written BEFORE implementation
+- [ ] Test/implementation ratio ≥ 40%
+- [ ] Mock usage justified (if >30% mock density)
 
-**执行方式**：每个 REQ 完成后，orchestrator 调用 `UpdateMemory` 存储 permanent learnings：
-- 架构决策 → `expert_experience` 类型
-- 接口约定/全局规范 → `development_practice_specification` 类型
-- 项目结构发现 → `project_introduction` 类型
+**Verification Layers**:
+- [ ] L1: typecheck + lint pass
+- [ ] L1b: Test-first ratio check pass
+- [ ] L2: **FULL regression tests** (all tests, not just @test REQ-XXX)
+- [ ] L3: coverage ≥ 80%
 
-### 三层验证 Gate 增强（替代 PostToolUse Hook）
+**Learnings Persisted**:
+- [ ] Permanent: [N items, list key ones]
+- [ ] Contextual: [N items, sliding window]
+- [ ] `gstack/learn` called
 
-在 Qoder 中，三层验证 Gate 增加 principles 检查步骤：
+**State Updated**:
+- [ ] AGENTS.md updated (orchestrator)
+- [ ] progress.log atomically written
+- [ ] Git commit created (if PASS)
 
-| 层级 | 原验证 | Qoder 增强 |
-|------|--------|------------|
-| L1 | typecheck + lint | + **principles check**（`npx -y tsx src/principles/index.ts --files <changed> --format console`） |
-| L2 | 全量测试 | 无变化 |
-| L3 | coverage ≥ 80% | 无变化 |
+**Next Step**: [REQ-YYY title / COMPLETE / BLOCKED]
+```
 
-> **注意**：principles check 仅在 src/principles/ 存在时执行（非 xp-gate 项目跳过）。
+**Eval Criteria** (Issue #120, #121):
+- ✅ L2 pass: Structured execution plan visible (checklist format)
+- ✅ L3 pass: All 7 workflow steps followed, full regression tests run
+- ❌ Fail: Missing checklist, partial tests, context pollution
 
 ---