ralph-verification

name	ralph-verification
description	Ralph Verification — AI Agent 驱动的结构化软件开发流程框架。 面向通用 Agent（OpenClaw / Hermes / 等），将编码任务委派给 Claude Code / Kimi CLI 等专用编码 Agent。 Router-in-the-Loop 架构：编写 PRD → 逐 Story 委派编码 Agent → Router 独立验收 → 失败则升级/纠偏。 支持双 Agent 调度、升级协议、PRD 审批门。
trigger	ralph|用ralph|按ralph流程|ralph方式|ralph开发
tools	["exec","terminal","read","write","script"]
user-invocable	true

Ralph Verification — Router-in-the-Loop 软件开发流程

定位：本 Skill 专为 OpenClaw、Hermes 等通用型 Agent 设计。通用 Agent 负责高层规划、PRD 编写、验收和流程编排；繁重的编码实现通过本 Skill 委派给 Claude Code、Kimi CLI 等专用编码 Agent。

核心逻辑：通用 Agent（你）= Router（编排层）→ 调用编码 Agent（执行层）→ 你独立验收 → 失败则写 feedback 升级。

---

前置条件 / Prerequisites

在首次使用前，必须确保以下依赖就绪。

必需依赖（Required）

工具	检查命令	安装方式	用途
Python 3	python3 --version	brew install python3 / apt install python3	运行调度脚本 scripts/invoke_agent.py
Git	git --version	brew install git / apt install git	版本控制、分支管理、diff 验收

可选依赖（至少安装一种编码 Agent）

工具	检查命令	安装方式	用途
Claude Code	claude --version	npm install -g @anthropic-ai/claude-code	默认编码 Agent（推荐）
Kimi CLI	kimi --version	参考 https://platform.moonshot.ai	备选编码 Agent

环境自动检查

运行以下命令检查环境：

bash {skillDir}/scripts/check-env.sh

如果缺少依赖，运行以下命令自动安装：

bash {skillDir}/scripts/setup.sh

OpenClaw 用户：使用 exec 工具运行上述命令。 Hermes 用户：使用 terminal 工具运行上述命令。

---

触发条件

当 User 说以下任意内容时，激活本 Skill：

• 「用 ralph 方式做 XXX」
• 「ralph 开发 XXX」
• 「按 ralph 流程 XXX」
• 「用 ralph 做 XXX」
• 或明确提到「ralph」+ 软件开发需求

---

工作流程（5 个阶段）

Phase 0 — 环境准备

每次触发本 Skill 时，先执行以下检查：

□ 运行 bash {skillDir}/scripts/check-env.sh 确认依赖就绪
□ 若缺少依赖，运行 bash {skillDir}/scripts/setup.sh --auto
□ 确认目标项目目录存在且有 git 仓库
□ 确认分支干净（无未提交变更）
□ 确认 .ralph/config.json 存在（setup.sh 会自动创建）

配置说明：.ralph/config.json 定义了可用的编码 Agent 及其调用方式。 默认配置使用 Claude Code 作为 agent1，Kimi CLI 作为 agent2。

Phase 1 — PRD 编写（Router 执行）

⚠️ 必须遵循 prd skill 流程！ 先问澄清问题，再生成 PRD，最后审批。

1.1 澄清问题（强制步骤）

Router 必须先问 3-5 个关键澄清问题，格式：

📋 开始规划 PRD，需要先确认几个问题：

1. **目标 Agent** — 使用哪个 Agent 执行开发？
   A. Claude Code（默认，高代码质量）
   B. Kimi CLI（成本优先）
   C. 双 Agent 组合（Claude×2 → Kimi×2）
   D. 其他: [指定]

2. **Story 拆分偏好** — 如何切分 User Stories？
   A. 最小化（3-5个），每个 Story 极小
   B. 平衡（5-8个），推荐
   C. 最大化（8-12个），每个 Story 完整

3. **Scope 边界** — 哪些不做？
   A. 只做核心功能
   B. 含基础测试
   C. 含完整测试 + 文档

4. **优先级规则** — Story 排序依据？
   A. 依赖关系（数据库→API→UI）
   B. 风险高低（高风险先做）
   C. 价值大小（高价值先做）

请回复如「1A, 2B, 3B, 4A」，或直接描述需求。

1.2 生成 PRD

收到回复后，Router 按以下结构生成 Markdown PRD（不是 JSON！）：

# PRD: [项目名称]

## 1. Introduction/Overview
[功能概述 + 解决什么问题]

## 2. Goals
- [具体可衡量的目标]
- ...

## 3. User Stories

### US-001: [标题]
**Description:** As a [user], I want [feature] so that [benefit].

**Acceptance Criteria:**
- [ ] 具体可验证的标准
- [ ] 另一个标准
- [ ] 类型检查/测试通过

[... 更多 Story ...]

## 4. Functional Requirements
- FR-1: [编号功能需求]
- FR-2: ...

## 5. Non-Goals (Out of Scope)
- [明确不做什么]

## 6. Design Considerations (Optional)
- [UI/UX/技术约束]

## 7. Technical Considerations (Optional)
- [已知约束/集成点]

## 8. Success Metrics
- [如何衡量成功]

## 9. Open Questions
- [待确认问题]

1.3 保存位置

项目根目录/
└── tasks/
    └── prd-[feature-name].md   ← PRD 存放位置（不是 prd.json）

同时初始化 progress.txt 和 .ralph/ 目录结构。

⭐ PRD 审批门（必须停等）：

• PRD 写完后，必须等待 User 审批后方可进入 Phase 2
• 发送消息给 User，格式：

  📋 PRD 已生成，请审批后再执行。
  
  项目：[project name]
  分支：[branchName]
  Story 数量：N 个
  
  ## Story 概览
  US-001: [title] - Priority N
  US-002: [title] - Priority N
  ...
  
  ## 关键决策确认
  - Agent 选择: [X]
  - Story 数量: [N]
  - Scope: [描述]
  
  请回复「确认」或提出修改意见。
  

• 若 User 有修改意见 → 吸收后更新 tasks/prd-[feature-name].md → 重新发送审批
• 若 User 回复「确认」→ 进入 Phase 2

PRD 编写原则：

• 每个 Story 应小而独立，单 Agent 一次上下文窗口可完成
• 验收标准必须可验证（具体、可测试、无歧义）
• 优先级考虑依赖关系（数据库 → API → UI）
• Story 数量控制在 5-8 个（除非 User 选择其他粒度）

Phase 2 — 迭代开发循环（Router 调度编码 Agent）

对每个 passes: false 的 Story 执行：

Step 1: Router 构建编码 Agent Prompt

• 加载 templates/agent_prompt.md 模板
• 注入当前 Story 详情 + Acceptance Criteria
• 若有上次驳回反馈 → 注入 feedback
• 保存到 .ralph/agent_prompt.md

Step 2: 调用编码 Agent 实现

• 根据 .ralph/config.json 和升级协议决定使用哪个 Agent
• 使用 terminal 或 exec 工具调用编码 Agent CLI
• 等待 Agent 完成并 commit

默认调用方式：

# Claude Code (Print Mode, 非交互)
claude --dangerously-skip-permissions --print "$(cat .ralph/agent_prompt.md)"

# Kimi CLI
kimi --quiet -w . -p "$(cat .ralph/agent_prompt.md)"

Step 3: Router 独立验收

• git diff HEAD~1 查看变更
• 逐条对照 Acceptance Criteria 检查
• 运行项目测试（如有）
• 给出判定: ✅ PASS / ❌ FAIL

结果处理：

• PASS → 更新 prd.json 设 passes: true → 追加 progress.txt → 下一 Story
• FAIL → 驳回计数 +1 → 写 feedback.txt（具体、可操作）→ 进入 Phase 2.5

Phase 2.5 — 升级协议（Escalation Protocol）

Story 验收失败
    │
    ├─ agent1_rejections < 2
    │   └─ Agent1 修复: Router 写 feedback.txt → Agent1 复验
    │                        ┌─ PASS → 下一 Story
    │                        └─ FAIL → agent1_rejections + 1
    │
    ├─ agent1_rejections == 2
    │   └─ ⚠️ 升级 Agent2 介入
    │       └─ Agent2 修复: Router 写 feedback.txt → Agent2 复验
    │                            ┌─ PASS → 下一 Story
    │                            └─ FAIL → agent2_rejections + 1
    │
    ├─ agent2_rejections == 2
    │   └─ ⚠️ 升级 Router 直接修复
    │       └─ Router 写代码修复
    │           ┌─ 成功 → 标记 passes: true
    │           └─ 失败 → 升级给 User
    │
    └─ router_attempts == 1
        └─ 🚨 升级给 User（人工决策）

升级给 User 时：停手，汇报问题症结 + 已尝试方案，等待人工决策。

Phase 3 — 全量验收

所有 Stories passes: true 后：

□ 运行全量测试套件
□ 检查是否有未提交变更
□ 生成开发总结报告
□ 标记 PRD status: "complete"

Phase 4 — 交付

• 汇报完成情况（Story 列表 + 状态 + 各 Agent 贡献统计）
• 列出关键文件变更
• 提供下一步建议

---

验收协议（Router 验收标准）

验收检查清单

对每个 Story 的变更，必须逐项检查：

1. 功能完整性 — 是否实现了所有 Acceptance Criteria？
2. 代码质量 — 是否遵循项目现有代码风格？无明显的代码异味？
3. 测试通过 — 现有测试是否全部通过？新增代码是否有对应测试？
4. 无副作用 — 是否引入了无关变更？是否破坏了其他功能？
5. Git 规范 — commit message 是否符合 feat: US-XXX - Title 格式？
6. 最小变更 — 变更是否聚焦在当前 Story，无越界实现？
7. Agent 过程规范 — 是否遵守各 Agent 的禁止规则？

各编码 Agent 禁止规则

Claude Code：

• ❌ 不修改 passes 字段（Router 验收后统一修改）
• ❌ 不写「Router 验收: ✅ PASS」—— 验收是 Router 职责
• ❌ 不跳过测试
• ❌ 不一次实现多个 Story

Kimi CLI：

• ❌ 不修改 passes 字段
• ❌ 不写「Router 验收: ✅ PASS」
• ❌ 不跳过测试
• ❌ 不一次实现多个 Story
• ❌ 不产生多个 commit（一个 Story 一个 commit）

驳回反馈格式

驳回时必须给出具体、可操作的反馈：

## ❌ Story US-XXX 验收驳回（第 N 次 by [Agent1/Agent2]）

### 未通过的验收标准
- [ ] 标准1：具体哪里没通过

### 需要修复的问题
1. **问题描述** (文件路径:行号)
   - 当前行为: ...
   - 期望行为: ...
   - 修复建议: ...

### 通过的部分（给予肯定）
- ✅ 标准2：已正确实现

---

文件结构

项目根目录/
├── tasks/
│   └── prd-[feature-name].md  ← Router 生成，Agent 只读（Markdown 格式）
├── progress.txt               ← Router + Agent 共同维护
│                              记录每个 Story 的实现过程、验收结果和学习
├── .ralph/
│   ├── config.json          ← Agent CLI 配置（默认 Claude + Kimi）
│   ├── feedback.txt         ← Router 写入的驳回反馈（临时）
│   └── agent_prompt.md      ← 当前轮的 Agent prompt（临时）
├── scripts/
│   ├── invoke_agent.py      ← 核心调度脚本
│   ├── check-env.sh         ← 环境依赖检查
│   └── setup.sh             ← 环境自动配置
└── templates/
    ├── agent_prompt.md      ← Agent Prompt 模板
    ├── claude_prompt.md     ← Claude 专用 Prompt（可选）
    └── prd_template.json    ← PRD 空模板

---

Agent Prompt 模板

见 templates/agent_prompt.md。关键约定：

• Agent 只实现指定 Story，不越界
• Agent 不修改 passes 字段（Router 验收后统一修改）
• Agent 完成后输出 <ralph>STORY_DONE</ralph> 信号
• 若有 feedback.txt，Agent 必须优先处理反馈中的问题

---

陷阱与注意事项

1. 编码 Agent 特性差异

Claude Code：

• ✅ 代码质量可以很高
• ❌ 过程纪律容易出错（commit 不全、越权写验收）
• 应对：prompt 中 FORBIDDEN 反复强调，Router 验收严查过程

Claude Code subprocess 调用陷阱：

• ❌ 不要用 stdin=subprocess.PIPE + input=prompt — Claude 的 --print 不接受 stdin
• ✅ 正确方式：subprocess.run(["claude", "--print", prompt], ...) — prompt 作为 positional argument
• ❌ 不要用 Python 3.10+ 语法 dict | None — 系统默认 Python 可能是 3.9
• ✅ 正确方式：用 Optional[dict] from typing

Kimi CLI：

• --quiet 输出干净，无结构化噪声
• Kimi 输出 <ralph>STORY_DONE</ralph> 时机与 Claude 相同
• 若超步数限制，加 --max-steps-per-turn 50
• Kimi session 可 resume：kimi -r <session_id>
• ⚠️ subprocess 调用：subprocess.run(["kimi", "--quiet", "-w", project_dir, "-p", prompt], ...)

2. Router 验收要严

• 验收时先 git status — 检查是否有未提交变更
• 验收时检查 progress.txt 是否有「Router 验收」字样（Agent 越权模式）
• 反馈要极其具体 — 文件路径、当前行为、期望行为
• 纠偏反馈写完后立即保存到 feedback.txt，再调用 Agent

3. 升级链路关键原则

• Agent 切换时必须重置上下文：每次切换 Agent，feedback.txt 包含完整问题描述
• Router 介入写代码时：直接用 write_file/patch 等工具，不通过 Agent CLI
• 升级到 User 时：停手等指示，不继续尝试

4. 超时处理

• 单 Story 超时 300s → 驳回并视为一次失败
• Agent 后台运行时用 notify_on_complete=true 自动通知
• Kimi 若出现步数限制，加 --max-steps-per-turn 50 或更高

5. Git 状态检查

• 每次调用 Agent 前确认 working tree clean
• 验收时第一件事：git status + git diff HEAD~1 --stat
• 验收时确认 commit 数 = 1（单 Story 单 commit 原则）

---

一键安装

本 Skill 支持一键安装到 OpenClaw 或 Hermes：

# 自动检测并安装
bash install.sh

# 指定目标安装
bash install.sh --target openclaw
bash install.sh --target hermes

安装脚本会自动：

1. 检测 OpenClaw / Hermes 环境
2. 将 Skill 复制到正确的 skills 目录
3. 运行 scripts/setup.sh 检查并安装依赖
4. 初始化 .ralph/config.json

---

版本历史

• v1.8 (2026-05-03): 重大变更：PRD 格式从 JSON 改为 Markdown，强制先问澄清问题再生成 PRD。PRD 存放位置改为 tasks/prd-[feature-name].md。
• v1.7 (2026-05-03): 新增一键安装支持（install.sh + setup.sh + check-env.sh）。SKILL.md 增加 trigger/tools/前置条件声明，适配 OpenClaw 和 Hermes 技能标准。
• v1.6 (2026-05-03): 新增 PRD 审批门，Phase 1 完成后必须等待 User 确认。去除特定人名依赖，适配开源即插即用。
• v1.5 (2026-05-02): 修复 Python 3.9 兼容性。修复 Claude CLI 调用方式。
• v1.4 (2026-05-02): Kimi CLI 参数修正：--print -y → --quiet。
• v1.3 (2026-05-02): 支持双 Agent（Claude + Kimi）。升级链路更新。
• v1.2 (2026-05-02): 新增 Phase 2.5 升级协议。
• v1.1 (2026-05-02): 触发测试完成，更新陷阱章节。
• v1.0 (2026-05-02): 初始版本，基于 ralph v0 原版增强 Router 验收环。