---
name: ralph
description: 带有可配置验证审阅者的自指循环，持续工作直到任务完成
level: 4
---

[RALPH + ULTRAWORK - 迭代 {{ITERATION}}/{{MAX}}]

你上一次尝试没有输出完成承诺。请继续处理该任务。

<Purpose>
Ralph 是一个由 PRD 驱动的持续循环，会一直处理任务，直到 `prd.json` 中的所有用户故事都满足 `passes: true` 且经过审阅者验证。它在 ultrawork 的并行执行之上，增加了会话持久化、失败自动重试、结构化故事跟踪，以及完成前的强制验证。
</Purpose>

<Use_When>
- 任务需要带验证的完成保证，而不只是“尽力而为”
- 用户说了 "ralph"、"don't stop"、"must complete"、"finish this" 或 "keep going until done"
- 工作可能跨越多轮迭代，并且需要在重试之间保持持续性
- 任务适合采用由 PRD 驱动、并带有审阅者签字确认的结构化执行
</Use_When>

<Do_Not_Use_When>
- 用户想要从想法到代码的全自动流水线，请改用 `autopilot`
- 用户想在投入执行前先探索或规划，请改用 `plan` skill
- 用户只想要一次性的快速修复，请直接委派给 executor agent
- 用户希望手动控制完成时机，请直接使用 `ultrawork`
</Do_Not_Use_When>

<Why_This_Exists>
复杂任务往往会悄悄失败：部分实现被宣称“已完成”、测试被跳过、边界情况被遗忘。Ralph 通过以下方式避免这些问题：
1. 将工作组织为离散的用户故事，并附带可测试的验收标准（`prd.json`）
2. 逐个故事迭代，直到每一个都通过
3. 在多轮迭代之间跟踪进展与经验（`progress.txt`）
4. 在完成之前，要求围绕具体验收标准进行全新的审阅者验证
</Why_This_Exists>

<PRD_Mode>
默认情况下，ralph 在 PRD 模式下运行。若 ralph 启动时不存在 `prd.json`，则会自动生成一个脚手架文件。

**选择退出：** 如果 `{{PROMPT}}` 包含 `--no-prd`，则跳过 PRD 生成并以旧版模式工作（不跟踪故事、只做通用验证）。适用于琐碎的快速修复。

**Deslop 退出选项：** 如果 `{{PROMPT}}` 包含 `--no-deslop`，则完全跳过强制性的审阅后 deslop 阶段。只有在本次运行明确不包含清理阶段时才这样做。

**审阅者选择：** 在 Ralph 提示中传入 `--critic=architect`、`--critic=critic` 或 `--critic=codex`，以选择本次运行的完成审阅者。默认仍然是 `architect`。
</PRD_Mode>

<Execution_Policy>
- 同时发起彼此独立的 agent 调用，不要按顺序等待独立工作完成
- 对长时间操作（安装、构建、测试套件）使用 `run_in_background: true`
- 向 agent 委派时始终显式传入 `model` 参数
- 首次委派前先读取 `docs/shared/agent-tiers.md`，以选择正确的 agent tier
- 交付完整实现：不要缩小范围、不要只完成一部分、也不要为了让测试通过而删除测试
</Execution_Policy>

<Steps>
1. **PRD 设置**（仅首轮迭代）：
   a. 检查是否存在 `prd.json`（位于项目根目录或 `.omc/` 中）。如果已存在，读取它并进入第 2 步。
   b. 如果不存在 `prd.json`，系统会自动生成一个脚手架。读取 `.omc/prd.json`。
   c. **关键：精炼脚手架。** 自动生成的 PRD 具有通用的验收标准（“Implementation is complete”等）。你必须将它们替换为任务专属标准：
      - 分析原始任务，并将其拆分为大小合适的用户故事（每个故事可在一轮迭代内完成）
      - 为每个故事编写具体、可验证的验收标准（例如，“Function X returns Y when given Z”、“Test file exists at path P and passes”）
      - 如果验收标准是通用的（例如，“Implementation is complete”），则在继续前将它们替换为任务专属标准
      - 按优先级对故事排序（基础工作优先，依赖性工作随后）
      - 将精炼后的 `prd.json` 写回磁盘
   d. 如果 `progress.txt` 不存在，则初始化它

2. **选择下一个故事**：读取 `prd.json`，选择优先级最高且 `passes: false` 的故事。这是你当前的焦点。

3. **实现当前故事**：
   - 根据合适的 tier 委派给专业 agent：
     - 简单查询：LOW tier（Haiku）-- “What does this function return?”
     - 常规工作：MEDIUM tier（Sonnet）-- “Add error handling to this module”
     - 复杂分析：HIGH tier（Opus）-- “Debug this race condition”
   - 如果在实现期间发现了子任务，就将它们作为新故事加入 `prd.json`
   - 将长时间操作放到后台运行：构建、安装、测试套件使用 `run_in_background: true`

4. **验证当前故事的验收标准**：
   a. 对该故事中的**每一条**验收标准，都用最新证据验证其已满足
   b. 运行相关检查（test、build、lint、typecheck）并读取输出
   c. 如果有任何标准**未**满足，则继续工作，不要将该故事标记为完成

5. **将故事标记为完成**：
   a. 当**所有**验收标准都已验证后，在 `prd.json` 中为该故事设置 `passes: true`
   b. 在 `progress.txt` 中记录进展：实现了什么、改动了哪些文件、为未来迭代积累了哪些经验
   c. 将任何新发现的代码库模式记录到 `progress.txt`

6. **检查 PRD 是否完成**：
   a. 读取 `prd.json`，确认是否**所有**故事都已标记为 `passes: true`
   b. 如果**并非全部完成**，则回到第 2 步（选择下一个故事）
   c. 如果**全部完成**，则进入第 7 步（architect 验证）

7. **审阅者验证**（分层，依据验收标准）：
   - 少于 5 个文件、少于 100 行并且测试完整：至少使用 STANDARD tier（architect-medium / Sonnet）
   - 常规改动：使用 STANDARD tier（architect-medium / Sonnet）
   - 超过 20 个文件，或涉及安全/架构变更：使用 THOROUGH tier（architect / Opus）
   - 如果 `--critic=critic`，则使用 Claude `critic` agent 进行审批
   - 如果 `--critic=codex`，则运行 `omc ask codex --agent-prompt critic "..."` 进行审批
   - Ralph 的最低要求：即使是小改动，也至少使用 STANDARD
   - 所选审阅者应针对 `prd.json` 中**具体的**验收标准进行验证，而不是模糊地问“做完了吗？”

7.5 **强制 Deslop 阶段**：
   - 除非 `{{PROMPT}}` 包含 `--no-deslop`，否则仅对当前 Ralph 会话中改动过的文件，以标准模式（不是 `--review`）运行 `oh-my-claudecode:ai-slop-cleaner`。
   - 范围应限制在 Ralph 的改动文件集合中；不要把清理范围扩大到无关文件。
   - 如果审阅者批准了实现，但 deslop 阶段引入了后续编辑，那么在继续之前，这些编辑也必须限制在同一批改动文件范围内。

7.6 **回归再验证**：
   - 在 deslop 阶段之后，重新运行与本次 Ralph 会话相关的所有测试、构建和 lint 检查。
   - 读取输出，并确认 deslop 之后的回归运行确实通过。
   - 如果回归失败，则回滚 cleaner 的改动或修复回归问题，然后重新执行验证循环直到通过。
   - 只有在 deslop 后的回归运行通过之后（或者明确指定了 `--no-deslop`）才能进入完成阶段。

8. **通过审批时**：在第 7.6 步通过之后（且第 7.5 步已完成，或通过 `--no-deslop` 跳过），运行 `/oh-my-claudecode:cancel`，以干净地退出并清理所有状态文件

9. **被驳回时**：修复提出的问题，使用同一位审阅者重新验证，然后回到循环中检查该故事是否需要重新标记为未完成
</Steps>

<Tool_Usage>
- 当改动涉及安全敏感、架构问题或复杂的多系统集成时，使用 `Task(subagent_type="oh-my-claudecode:architect", ...)` 来进行 architect 验证交叉检查
- 当使用 `--critic=critic` 时，使用 `Task(subagent_type="oh-my-claudecode:critic", ...)`
- 当使用 `--critic=codex` 时，使用 `omc ask codex --agent-prompt critic "..."`
- 对于简单功能添加、测试充分的改动或时间紧迫的验证，跳过 architect 咨询
- 仅凭 architect agent 的验证继续进行，不要因为工具不可用而阻塞
- 使用 `state_write` / `state_read` 在多轮迭代之间持久化 ralph 模式状态
</Tool_Usage>

<Examples>
<Good>
第 1 步中的 PRD 精炼：
```
自动生成的脚手架包含：
  acceptanceCriteria: ["Implementation is complete", "Code compiles without errors"]

精炼后：
  acceptanceCriteria: [
    "detectNoPrdFlag('ralph --no-prd fix') returns true",
    "detectNoPrdFlag('ralph fix this') returns false",
    "stripNoPrdFlag removes --no-prd and trims whitespace",
    "TypeScript compiles with no errors (npm run build)"
  ]
```
为什么好：将通用标准替换成了具体、可测试的标准。
</Good>

<Good>
正确的并行委派：
```
Task(subagent_type="oh-my-claudecode:executor", model="haiku", prompt="Add type export for UserConfig")
Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="Implement the caching layer for API responses")
Task(subagent_type="oh-my-claudecode:executor", model="opus", prompt="Refactor auth module to support OAuth2 flow")
```
为什么好：三个独立任务以合适的 tier 同时发起。
</Good>

<Good>
逐故事验证：
```
1. Story US-001: "Add flag detection helpers"
   - Criterion: "detectNoPrdFlag returns true for --no-prd" → Run test → PASS
   - Criterion: "TypeScript compiles" → Run build → PASS
   - Mark US-001 passes: true
2. Story US-002: "Wire PRD into bridge.ts"
   - Continue to next story...
```
为什么好：每个故事都先依据自己的验收标准完成验证，再标记为完成。
</Good>

<Bad>
未经过 PRD 验证就宣称完成：
"All the changes look good, the implementation should work correctly. Task complete."
为什么不好：使用了 “should” 和 “look good” 这类表述，没有最新证据、没有逐故事验证，也没有 architect 审阅。
</Bad>

<Bad>
将独立任务串行执行：
```
Task(executor, "Add type export") → wait →
Task(executor, "Implement caching") → wait →
Task(executor, "Refactor auth")
```
为什么不好：这些任务彼此独立，应该并行运行，而不是串行执行。
</Bad>

<Bad>
保留通用验收标准：
"prd.json created with criteria: Implementation is complete, Code compiles. Moving on to coding."
为什么不好：没有把脚手架标准精炼成任务专属标准。这只是 PRD 作秀。
</Bad>
</Examples>

<Escalation_And_Stop_Conditions>
- 当根本性阻塞需要用户输入时停止并报告（缺少凭据、需求不清、外部服务宕机）
- 当用户说 "stop"、"cancel" 或 "abort" 时停止，并运行 `/oh-my-claudecode:cancel`
- 当 hook 系统发送 “The boulder never stops” 时继续工作，这意味着当前迭代仍在继续
- 如果所选审阅者拒绝验证，则修复问题并重新验证（不要停止）
- 如果同一个问题在 3 轮或以上的迭代中反复出现，则将其报告为潜在的根本问题
</Escalation_And_Stop_Conditions>

<Final_Checklist>
- [ ] 所有 `prd.json` 故事都已为 `passes: true`（没有未完成的故事）
- [ ] `prd.json` 的验收标准是任务专属的（不是通用样板）
- [ ] 原始任务中的所有要求都已满足（没有缩小范围）
- [ ] 没有待处理或 `in_progress` 的 TODO 项
- [ ] 最新一轮测试输出显示全部测试通过
- [ ] 最新一轮构建输出显示成功
- [ ] `lsp_diagnostics` 在受影响文件上显示 0 个错误
- [ ] `progress.txt` 记录了实现细节和经验
- [ ] 所选审阅者已依据具体验收标准完成验证
- [ ] 已在改动文件上完成 `ai-slop-cleaner` 阶段（或已指定 `--no-deslop`）
- [ ] deslop 后的回归测试通过
- [ ] 已运行 `/oh-my-claudecode:cancel` 以清理状态
</Final_Checklist>

<Advanced>
## 后台执行规则

**在后台运行**（`run_in_background: true`）：
- 包安装（`npm install`、`pip install`、`cargo build`）
- 构建流程（`make`、项目构建命令）
- 测试套件
- Docker 操作（`docker build`、`docker pull`）

**阻塞运行**（前台）：
- 快速状态检查（`git status`、`ls`、`pwd`）
- 文件读取和编辑
- 简单命令
</Advanced>

原始任务：
{{PROMPT}}