---
description: "Start Ralph Wiggum loop in current session"
argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT] [--verify \"CHECK\" ...]"
allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
hide-from-slash-command-tool: "true"
---

# Ralph Loop Command

<!--
  minimal-agent 注意：以下 ```! ``` 块是 Claude Code 专有的 shell-on-command
  语法，minimal-agent **不会执行**它。GoalState 的初始化（goal.md / phase.md
  / completion.md 等）由本插件的 plugin.ts 在进循环前自动完成，
  不需要 setup 脚本。该块保留在这里只是为了与原版 Claude Code 兼容。
-->

Execute the setup script to initialize the Ralph loop:

```!
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
```

Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.

CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

---

## 本插件管理的状态文件

`.minimal-agent-ralph-wiggum/` 目录下的所有文件（goal.md / phase.md / completion.md /
progress.md / learnings.md / decisions.md）**由本插件自动创建并维护**，你不需要主动
读写它们。每轮迭代开始时，插件会把当前目标、阶段、最近进度、关键决策、教训自动拼接到
你的 prompt 头部（freshContext），你**专注按头部信息行动**即可。

## 阶段工作流

循环会自动管理阶段转换（PLAN → BUILD → VERIFY → HEAL → DONE），但你应主动配合当前阶段：

- **PLAN 阶段**：分析任务、拆解步骤、识别风险
- **BUILD 阶段**：按计划实现代码，每次聚焦一个子任务
- **VERIFY 阶段**：运行测试、检查输出、验证功能
- **HEAL 阶段**：定位问题根因、修复 bug、避免回归

## 完成哨兵

当且仅当任务真正完成时，输出（驱动进入验证门）：
```
<promise>DONE</promise>
```
也可使用 `--completion-promise` 指定的自定义短语，驱动同样认可。

如果发现**当前方案**根本不可行，需要换方案重新规划（目标不变）：
```
<PROMISE>NEED_REPLAN</PROMISE>
```

如果**目标本身**有问题、无法用任何方案达成，需要人工修订目标时（独立逃生门，循环干净停止）：
```
<PROMISE>NEED_GOAL_REVISION</PROMISE>
```
> 区别：NEED_REPLAN = 换方案（目标不变）；NEED_GOAL_REVISION = 目标本身有问题，请人工介入。

## 验证门 --verify

命中完成哨兵后，驱动会运行所有 `--verify` CHECK，**全部通过才真正退出**，否则回 BUILD 继续。
可重复多次，支持 4 种 CHECK 类型：

- `shell:<命令>` —— 退出码 0 = 通过（Windows 走 `cmd /c`，其余 `bash -c`）
- `file_exists:<路径>` —— 文件存在
- `file_contains:<文件>:<正则>` —— 文件内容匹配正则
- `test_count:<最小数>` —— 跑 `bun test`，统计到的通过数 ≥ 最小数

示例：
```
/ralph-loop "实现并测试缓存层" --verify "shell:bun test" --verify "file_exists:src/cache.ts"
```

## 踩坑记录

如果在工作中发现任何值得记录的教训（坑、陷阱、最佳实践），用 `<learning>…</learning>` 标记：
```
<learning>直接写文件前必须先 Read，否则 Edit 会报错</learning>
```
驱动每轮自动把 learning 存档到 `.minimal-agent-ralph-wiggum/learnings.md`，后续迭代会自动读入上下文复用。
