Back to Details

task-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Task Loop

任务循环

Scaffold a self-contained loop directory from an existing backlog. The directory contains everything a fresh agent session needs to pick up a task, execute it, and hand off to the next iteration — with no session memory between runs.
基于现有待办清单搭建独立的循环目录结构。该目录包含全新Agent会话承接任务、执行任务、并流转到下一轮迭代所需的全部内容，且不同运行批次之间不存在会话记忆。

When to use

使用场景

Invoke when the user has a backlog (from 
/task-plan
, hand-written, or any structured task list) and wants to run it through an automated agent loop. The output is a directory with PROMPT.md, run-log.md, and a shared .gitignore.
当用户拥有待办清单（来自 
/task-plan
、手写或任何结构化任务列表），并希望通过自动化Agent循环运行该清单时调用本工具。输出为包含PROMPT.md、run-log.md和共享.gitignore的目录。

Process

处理流程

1. Locate the backlog

1. 定位待办清单

Accept a backlog file path. If not provided, look for:
  • A file the user recently created or discussed
  • Files matching 
    TASKS/*/backlog.md
    or 
    *TASKS*.md
  • Any markdown file with checkbox tasks
Ask if unclear.
接收待办清单文件路径。如果未提供，查找以下内容：
  • 用户最近创建或讨论过的文件
  • 匹配 
    TASKS/*/backlog.md
    或 
    *TASKS*.md
    的文件
  • 任何包含复选框任务的markdown文件
如果不明确则询问用户。

2. Read and understand the backlog

2. 读取并理解待办清单

Read the backlog to understand:
  • Task shape (what fields each task has)
  • Verification patterns (global rules, per-task criteria, referenced docs)
  • Dependencies between tasks
  • Any reference material mentioned in the backlog header
This understanding drives how PROMPT.md is adapted.
读取待办清单，明确以下信息：
  • 任务结构（每个任务包含的字段）
  • 校验规则（全局规则、单任务校验标准、引用的文档）
  • 任务之间的依赖关系
  • 待办清单头部提到的所有参考材料
这些信息会指导PROMPT.md的适配生成。

3. Ask about execution context

3. 询问执行上下文

Ask the user:
  • "Are there docs or skills that will help execute these tasks?" (e.g. Figma workflow, testing guide, API docs)
  • "Any project-specific verification rules beyond what's in the backlog?"
  • "What timeout per iteration makes sense?" (helps with the suggested run command)
向用户确认：
  • "Are there docs or skills that will help execute these tasks?" （例如Figma工作流、测试指南、API文档）
  • "Any project-specific verification rules beyond what's in the backlog?"
  • "What timeout per iteration makes sense?"（用于生成建议的运行命令）

4. Generate the loop directory

4. 生成循环目录

If the backlog is already in a 
TASKS/<name>/
directory, generate files alongside it. If not, ask where to create the directory or suggest 
TASKS/<name>/
based on the backlog content.
Generate these files:
如果待办清单已经放在 
TASKS/<name>/
目录下，则在同级生成文件。如果没有，询问用户要创建目录的位置，或者根据待办清单内容建议使用 
TASKS/<name>/
路径。
生成以下文件：

PROMPT.md

PROMPT.md

The loop contract. Self-contained — the agent reads this one file and has the complete protocol. Built from the core protocol template (read references/loop-protocol.md) plus task-specific adaptations:
  • File paths — point to this directory's loop-state.md, run-log.md, and backlog.md
  • Loop completion token — emit 
    __PROMISE_RL_DONE__
    as a standalone final line when no unchecked tasks remain so the default 
    rl
    promise-token handling can stop cleanly. This is the Ralph-loop “completion promise” expressed as a plain token.
  • Verification rules — extracted from the backlog's global and per-task verification patterns. Reference external docs if the backlog mentions them
  • Dependency handling — if the backlog has a dependency graph, add instructions to respect it when picking the next task
  • Reference docs — if the user mentioned helpful docs or skills, add them to the prompt so the agent knows where to look
The prompt must start with a level-1 heading (markdown linter requirement).
循环约定文件，内容独立完整：Agent只需读取这一个文件就能获取完整的执行协议。基于核心协议模板（参考 references/loop-protocol.md）加上任务专属适配生成：
  • 文件路径：指向当前目录下的loop-state.md、run-log.md和backlog.md
  • 循环完成标记：当没有未勾选的任务时，单独输出 
    __PROMISE_RL_DONE__
    作为最后一行，这样默认的
    rl
    promise-token处理逻辑可以干净地停止运行。这是Ralph循环“完成承诺”的纯标记表达形式。
  • 校验规则：从待办清单的全局和单任务校验规则中提取。如果待办清单提到了外部文档，需要引用这些文档
  • 依赖处理：如果待办清单包含依赖关系图，添加指令要求Agent选择下一个任务时遵循依赖关系
  • 参考文档：如果用户提到了有用的文档或技能，将其添加到prompt中，方便Agent查找参考
Prompt必须以一级标题开头（markdown linter要求）。

run-log.md

run-log.md

Empty file with 
# Run Log
header. Entries are appended by the agent during execution — one entry per completed or blocked task.
Entry format:
markdown
undefined
带有 
# Run Log
头部的空文件。Agent在执行过程中会追加内容，每个完成或阻塞的任务对应一条记录。
记录格式：
markdown
undefined

<ISO-timestamp> | <task-id> | <done|blocked>

<ISO-timestamp> | <task-id> | <done|blocked>

  • Commit: <sha>
  • Verification: <what was run>
  • Surprises: <anything unexpected, or "none">
undefined
  • Commit: <sha>
  • Verification: <what was run>
  • Surprises: <anything unexpected, or "none">
undefined

TASKS/.gitignore

TASKS/.gitignore

If a 
TASKS/.gitignore
doesn't already exist in the parent directory, create one containing 
loop-state.md
. This keeps ephemeral state out of version control while allowing clean deletion of the entire task directory.
如果父目录下不存在 
TASKS/.gitignore
，则创建该文件，内容为 
loop-state.md
。这样可以避免临时状态文件进入版本控制，同时支持干净删除整个任务目录。

5. Present the output

5. 输出结果展示

Show the user:
  • The generated directory structure
  • The PROMPT.md content (or a summary if long)
  • How to run it, e.g.: 
    rl <n> -t 30m -- claude -p "Read and follow TASKS/<name>/PROMPT.md"
向用户展示：
  • 生成的目录结构
  • PROMPT.md的内容（如果过长则展示摘要）
  • 运行方法，例如： 
    rl <n> -t 30m -- claude -p "Read and follow TASKS/<name>/PROMPT.md"

PROMPT.md anatomy

PROMPT.md结构

Every generated PROMPT.md has these sections:
  1. Heading — 
    # Prompt
  2. Preamble — "You are running in an automated loop. Read these files before doing anything else:" followed by the three file paths
  3. Protocol — the state machine:
    • No state file or status 
      done
      → append run-log entry, pick next task
    • No unchecked tasks remain → emit 
      __PROMISE_RL_DONE__
      and exit
    • Status 
      in_progress
      or 
      verifying
      → resume from checklist
    • Status 
      blocked
      → log blocker, skip to next task
  4. Verification — rules adapted from the backlog, referencing external docs where appropriate
  5. Completion rule — the four conditions that must all be true before marking a task done
  6. Surprises — instructions to capture unexpected findings
Read references/loop-protocol.md for the core template. Adapt it — don't copy it verbatim. Each backlog has different verification needs and reference material.
每个生成的PROMPT.md都包含以下部分：
  1. 标题 — 
    # Prompt
  2. 前言 — "You are running in an automated loop. Read these files before doing anything else:" 后接三个文件路径
  3. 协议 — 状态机规则：
    • 无状态文件或状态为
      done
      → 追加运行日志记录，选择下一个任务
    • 无未勾选任务 → 输出 
      __PROMISE_RL_DONE__
      并退出
    • 状态为
      in_progress
      或
      verifying
      → 从检查点恢复执行
    • 状态为
      blocked
      → 记录阻塞原因，跳转到下一个任务
  4. 校验 — 从待办清单适配而来的规则，必要时引用外部文档
  5. 完成规则 — 标记任务为完成前必须全部满足的四个条件
  6. 意外情况 — 要求记录意外发现的说明
参考 references/loop-protocol.md 获取核心模板。需要适配模板，不要直接复制粘贴，每个待办清单都有不同的校验需求和参考材料。

loop-state.md

loop-state.md

Created at runtime by the agent, not pre-created by this skill. The agent creates it when claiming a task. Format:
markdown
---
current_task: <task-id>
status: in_progress | verifying | done | blocked
last_commit: ""
next_task: <task-id>
blockers: ""
---
由Agent在运行时创建，本技能不会预先创建。Agent认领任务时创建该文件，格式如下：
markdown
---
current_task: <task-id>
status: in_progress | verifying | done | blocked
last_commit: ""
next_task: <task-id>
blockers: ""
---

Checklist

Checklist

  • Code changes made
  • Verification passed
  • Backlog checkbox updated
  • Commit created
  • Code changes made
  • Verification passed
  • Backlog checkbox updated
  • Commit created

Surprises

Surprises

  • (none yet)

Gitignored via `TASKS/.gitignore` — changes every iteration, noisy in
version control. Clean deletion of the task directory removes it too.
  • (none yet)

通过 `TASKS/.gitignore` 忽略该文件：每轮迭代都会修改，放在版本控制中会产生大量噪音。删除任务目录时也会一并删除该文件。