ralph-script

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Script

Add

ralph-loop.sh

and

prompt.md

to the current project from bundled templates.

为当前项目从捆绑模板中添加

ralph-loop.sh

和

prompt.md

文件。

Workflow

工作流程

1. Parse arguments

1. 解析参数

Check if the user passed

--force

. If so, set

FORCE=true

and skip all interactive checks in step 2.

检查用户是否传入

--force

。如果是，设置

FORCE=true

并跳过步骤2中的所有交互式检查。

2. Check referenced files

2. 检查引用文件

The ralph loop references these files at runtime:

File	How it's used	Required format
`PLAN.md`	Loop continues while `- [ ]` checkboxes exist	Must contain `- [ ]` / `- [x]` markdown checkboxes
`PROBLEM.md`	Read for troubleshooting context	Any markdown
`PRD.md`	Read for troubleshooting context	Any markdown
`specs/README.md`	Read for troubleshooting context	Any markdown

For each file, check if it exists in the project root.

If a file is missing (and not

--force

): Warn the user. List all missing files in a single message. Do not offer to create them — just note they will need to exist before running the loop.

If PLAN.md exists: Read it and verify it contains

- [ ]

style checkboxes. If it uses a different task format (numbered lists,

TODO:

markers, other patterns), use AskUserQuestion to ask:

"PLAN.md uses [detected format] instead of
```
- [ ]
```
checkboxes. The ralph-loop.sh script checks for
```
- [ ]
```
to determine if tasks remain. Should I: (a) update the script's grep pattern to match your format, or (b) leave as-is (you'll convert PLAN.md yourself)?"
If (a): note the needed grep pattern change for step 3.

If prompt.md references files that don't exist (and not

--force

): Optionally ask whether to remove those references from the generated prompt.md. Only ask if 2+ referenced troubleshooting files are missing — if just one is missing, simply warn.

Ralph循环在运行时会引用以下文件：

文件	用途	要求格式
`PLAN.md`	当存在 `- [ ]` 复选框时循环继续	必须包含 `- [ ]` / `- [x]` 格式的Markdown复选框
`PROBLEM.md`	用于读取故障排查上下文	任意Markdown格式
`PRD.md`	用于读取故障排查上下文	任意Markdown格式
`specs/README.md`	用于读取故障排查上下文	任意Markdown格式

对每个文件，检查其是否存在于项目根目录。

如果文件缺失（且未使用
--force
）：向用户发出警告。在一条消息中列出所有缺失的文件。不要主动提出创建这些文件——只需提醒用户在运行循环前需要确保这些文件存在。

如果PLAN.md已存在：读取该文件并验证其是否包含

- [ ]

格式的复选框。如果使用了其他任务格式（如编号列表、

TODO:

标记或其他模式），使用AskUserQuestion询问用户：

"PLAN.md使用[检测到的格式]而非
```
- [ ]
```
复选框。ralph-loop.sh脚本通过检测
```
- [ ]
```
来判断是否还有剩余任务。我应该：(a) 更新脚本的grep匹配模式以适配你的格式，还是(b) 保持原样（你自行转换PLAN.md的格式）？"
如果选择(a)：记录步骤3中需要修改的grep匹配模式。

如果prompt.md引用的文件不存在（且未使用
--force
）：可选择询问用户是否要从生成的prompt.md中移除这些引用。仅当2个及以上被引用的故障排查文件缺失时才询问——如果仅缺失一个，只需发出警告。

3. Copy templates

3. 复制模板

Copy the template files from this skill's assets directory into the project root:

```
assets/ralph-loop.sh
```
→
```
./ralph-loop.sh
```
```
assets/prompt.md
```
→
```
./prompt.md
```

If either file already exists in the project, use AskUserQuestion to confirm overwrite (unless

--force

Apply any modifications determined in step 2 (e.g., adjusted grep pattern).

Make

ralph-loop.sh

executable:

bash

chmod +x ralph-loop.sh

将本技能资产目录中的模板文件复制到项目根目录：

```
assets/ralph-loop.sh
```
→
```
./ralph-loop.sh
```
```
assets/prompt.md
```
→
```
./prompt.md
```

如果项目中已存在任一文件，使用AskUserQuestion确认是否覆盖（除非使用

--force

）。

应用步骤2中确定的所有修改（例如，调整后的grep匹配模式）。

设置

ralph-loop.sh

为可执行权限：

bash

chmod +x ralph-loop.sh

4. Report

4. 报告

Print a summary:

Files created
Any warnings about missing referenced files
How to run:
```
./ralph-loop.sh
```
Remind that
```
jq
```
is optional but provides colored output with context usage tracking

打印摘要信息：

创建的文件
所有关于缺失引用文件的警告
运行方式：
```
./ralph-loop.sh
```
提醒用户
```
jq
```
为可选工具，但使用它可以提供带上下文使用跟踪的彩色输出