---
name: ralph-loop
description: Ralph Loop 自动化编码循环 - 让 AI 代理持续工作直到完成任务。支持 PLANNING（规划）和 BUILDING（构建）两种模式，使用 exec + process 工具监控进度。
allowed-tools: Read, Write, Edit, Exec, Process
---

# Ralph Loop (Agent Mode)

自动化 AI 编码代理循环工作流。

## 工作流程

```
需求定义 → PLANNING Loop → BUILDING Loop → 完成
```

1. **PLANNING Loop** - 创建/更新 IMPLEMENTATION_PLAN.md（不实现）
2. **BUILDING Loop** - 实现任务、运行测试、更新计划、提交

## 支持的 CLI

| CLI | 命令模式 | TTY 需求 |
|-----|---------|---------|
| OpenCode | `opencode run --model <MODEL> "$(cat PROMPT.md)"` | ✅ |
| Codex | `codex exec --full-auto "$(cat PROMPT.md)"` | ✅ |
| Claude Code | `claude --dangerously-skip-permissions "$(cat PROMPT.md)"` | ✅ |
| Pi | `pi --provider <PROVIDER> -p "$(cat PROMPT.md)"` | ✅ |
| Goose | `goose run "$(cat PROMPT.md)"` | ✅ |

## 使用方法

### 1. 准备项目文件

创建 `PROMPT.md`:
```markdown
# 目标
<你的任务描述>

## 参考文件
- specs/*.md
- IMPLEMENTATION_PLAN.md
```

创建 `AGENTS.md`:
```markdown
# 项目说明

## 测试命令
npm test

## 构建命令
npm run build
```

### 2. 启动循环

**PLANNING 模式**:
```bash
# 我会执行
exec(
  command: 'opencode run --model claude-opus-4 "$(cat PROMPT.md)"',
  workdir: "/path/to/project",
  background: true,
  pty: true,
  timeout: 3600
)
```

**BUILDING 模式**:
```bash
# 同上，但 PROMPT.md 内容不同
```

### 3. 监控进度

```bash
# 轮询状态
process(action: "poll", sessionId: "xxx")

# 查看日志
process(action: "log", sessionId: "xxx", offset: -30)
```

### 4. 检测完成

检查 `IMPLEMENTATION_PLAN.md`:
- `STATUS: PLANNING_COMPLETE` - 规划完成
- `STATUS: COMPLETE` - 构建完成

## 提示词模板

### PLANNING 模式

```markdown
You are running a Ralph PLANNING loop for this goal: <goal>.

Read specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.

Rules:
- Do not implement
- Do not commit
- Create a prioritized task list
- Write down questions if unclear

Completion:
When plan is ready, add: STATUS: PLANNING_COMPLETE
```

### BUILDING 模式

```markdown
You are running a Ralph BUILDING loop for this goal: <goal>.

Context: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md

Tasks:
1) Pick the most important task
2) Investigate code
3) Implement
4) Run backpressure commands from AGENTS.md
5) Update IMPLEMENTATION_PLAN.md
6) Update AGENTS.md with learnings
7) Commit with clear message

Completion:
When all done, add: STATUS: COMPLETE
```

## 安全注意事项

- 使用沙盒环境
- 设置合理超时
- 重要项目先备份
- 监控进度，不要过早终止

## 故障排除

| 问题 | 解决方案 |
|------|---------|
| CLI 卡住 | 确保 pty: true |
| 无法启动 | 检查 CLI 路径和 git 仓库 |
| 未检测到完成 | 验证 IMPLEMENTATION_PLAN.md 中的格式 |
| 超时 | 增加 timeout 参数 |

## 示例

### 完整工作流

1. 用户: "帮我实现用户认证模块"
2. 我创建 specs/auth.md, PROMPT.md, AGENTS.md
3. 我启动 PLANNING 循环
4. AI 生成 IMPLEMENTATION_PLAN.md
5. 我启动 BUILDING 循环
6. AI 逐个实现任务
7. 检测到 STATUS: COMPLETE
8. 完成！

## License

MIT