Back to Details

ralph-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ralph Loop — Python Orchestrator

Ralph Loop — Python 编排器

⚠️ IMPORTANT: This skill uses a Python orchestrator script. Do NOT execute arbitrary bash commands. Use 
Bash
ONLY to run 
ralph_loop.py
. All task commands (like 
/specs:task-implementation
) are shown to the user to execute manually.
⚠️ 重要提示：本技能使用Python编排器脚本。请勿执行任意bash命令。仅可使用
Bash
运行
ralph_loop.py
。所有任务命令（如
/specs:task-implementation
）均会展示给用户，由用户手动执行。

Overview

概述

The Ralph Loop applies Geoffrey Huntley's "Ralph Wiggum as a Software Engineer" technique to specification-driven development. It uses a Python orchestrator script that manages a state machine: one invocation = one step, state persisted in 
fix_plan.json
.
Key insight: Implementing + reviewing + syncing in one invocation explodes the context window. Solution: each loop iteration does exactly one step, saves state to 
fix_plan.json
, and stops. The next iteration resumes from saved state.
Key improvement: The Python script 
ralph_loop.py
handles all state management, task selection, and command generation. It does NOT execute task commands directly — it shows you the correct command to execute in your CLI.
Ralph Loop 应用了Geoffrey Huntley提出的“将Ralph Wiggum作为软件工程师”技术，用于规范驱动开发。它使用一个Python编排器脚本管理状态机：每次调用执行一个步骤，状态持久化存储在
fix_plan.json
中。
核心思路：在一次调用中同时完成实现、评审和同步会导致上下文窗口溢出。解决方案：每次循环迭代仅执行一个步骤，将状态保存到
fix_plan.json
后停止，下一次迭代从保存的状态恢复。
核心改进：Python脚本
ralph_loop.py
负责所有状态管理、任务选择和命令生成。它不会直接执行任务命令——而是向你展示在CLI中执行的正确命令。

When to Use

适用场景

  • User runs 
    /loop
    command for recurring automation
  • User asks to "automate implementation" or "run tasks in loop"
  • User wants to "iterate through tasks step-by-step" or "run workflow automation"
  • User needs "context window management" across multiple SDD commands
  • User wants to "process task range" from TASK-N to TASK-M
  • User needs multi-agent support (different CLIs for different tasks)
  • 用户运行
    /loop
    命令进行周期性自动化操作
  • 用户要求“自动化实现”或“循环运行任务”
  • 用户希望“逐步遍历任务”或“运行工作流自动化”
  • 用户需要跨多个SDD命令的“上下文窗口管理”
  • 用户希望处理从TASK-N到TASK-M的“任务范围”
  • 用户需要多Agent支持（不同任务使用不同CLI）

Architecture

架构

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ralph_loop.py │────▶│   fix_plan.json │────▶│  User executes  │
│   (orchestrator)│     │   (state file)  │     │  command in CLI │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                               │
         │                                               ▼
         │                                      ┌─────────────────┐
         └──────────────────────────────────────│   Task result   │
                                                │   (success/     │
                                                │   failure)      │
                                                └─────────────────┘
One Step Flow:
  1. Run 
    ralph_loop.py --action=loop
  2. Script reads 
    fix_plan.json
    and determines current step
  3. Script shows the command to execute (e.g., 
    /specs:task-implementation
    )
  4. User executes the command in their CLI
  5. User runs 
    ralph_loop.py --action=loop
    again
  6. Script updates state based on result and shows next command
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ralph_loop.py │────▶│   fix_plan.json │────▶│  User executes  │
│   (orchestrator)│     │   (state file)  │     │  command in CLI │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                               │
         │                                               ▼
         │                                      ┌─────────────────┐
         └──────────────────────────────────────│   Task result   │
                                                │   (success/     │
                                                │   failure)      │
                                                └─────────────────┘
单步骤流程：
  1. 运行
    ralph_loop.py --action=loop
  2. 脚本读取
    fix_plan.json
    并确定当前步骤
  3. 脚本展示要执行的命令（例如
    /specs:task-implementation
    ）
  4. 用户在CLI中执行该命令
  5. 用户再次运行
    ralph_loop.py --action=loop
  6. 脚本根据结果更新状态并展示下一个命令

State Machine

状态机

fix_plan.json state machine:
┌─────────────────────────────────────────────────────────────┐
│  state: "init"                                            │
│    → --action=start: Initialize fix_plan.json              │
│    → Load tasks from tasks/TASK-*.md files                │
│    → Apply task_range filter                              │
│                                                             │
│  state: "choose_task"                                      │
│    → Pick next pending task (within range, deps satisfied)│
│    → No tasks in range → state: "complete"               │
│    → Task found → state: "implementation"                │
│                                                             │
│  state: "implementation"                                  │
│    → Show /specs:task-implementation command             │
│    → User executes, then runs loop again                  │
│    → Next state: "review"                                │
│                                                             │
│  state: "review"                                          │
│    → Show /specs:task-review command                     │
│    → User reviews results, then runs loop again          │
│    → Issues found → state: "fix" (retry ≤ 3)             │
│    → Clean → state: "cleanup"                            │
│                                                             │
│  state: "fix"                                             │
│    → Show commands to fix issues                         │
│    → User applies fixes, then runs loop again            │
│    → Next state: "review"                                │
│                                                             │
│  state: "cleanup"                                         │
│    → Show /developer-kit-specs:specs-code-cleanup command│
│    → Next state: "sync"                                  │
│                                                             │
│  state: "sync"                                            │
│    → Show /specs:spec-sync-with-code command             │
│    → Next state: "update_done"                           │
│                                                             │
│  state: "update_done"                                     │
│    → Mark task done, commit git changes                  │
│    → Re-evaluate dependencies                            │
│    → state: "choose_task"                                │
│                                                             │
│  state: "complete" | "failed"                            │
│    → Print result, stop                                   │
└─────────────────────────────────────────────────────────────┘
fix_plan.json state machine:
┌─────────────────────────────────────────────────────────────┐
│  state: "init"                                            │
│    → --action=start: 初始化fix_plan.json                    │
│    → 从tasks/TASK-*.md文件加载任务                        │
│    → 应用task_range过滤器                                │
│                                                             │
│  state: "choose_task"                                      │
│    → 选择下一个待处理任务（在范围内，依赖已满足）            │
│    → 范围内无任务 → state: "complete"                     │
│    → 找到任务 → state: "implementation"                  │
│                                                             │
│  state: "implementation"                                  │
│    → 展示/specs:task-implementation命令                   │
│    → 用户执行后，再次运行loop                              │
│    → 下一状态: "review"                                  │
│                                                             │
│  state: "review"                                          │
│    → 展示/specs:task-review命令                           │
│    → 用户评审结果后，再次运行loop                          │
│    → 发现问题 → state: "fix"（最多重试3次）               │
│    → 无问题 → state: "cleanup"                            │
│                                                             │
│  state: "fix"                                             │
│    → 展示修复问题的命令                                   │
│    → 用户应用修复后，再次运行loop                          │
│    → 下一状态: "review"                                  │
│                                                             │
│  state: "cleanup"                                         │
│    → 展示/developer-kit-specs:specs-code-cleanup命令        │
│    → 下一状态: "sync"                                    │
│                                                             │
│  state: "sync"                                            │
│    → 展示/specs:spec-sync-with-code命令                   │
│    → 下一状态: "update_done"                             │
│                                                             │
│  state: "update_done"                                     │
│    → 标记任务完成，提交git变更                            │
│    → 重新评估依赖关系                                      │
│    → state: "choose_task"                                │
│                                                             │
│  state: "complete" | "failed"                            │
│    → 打印结果，停止运行                                   │
└─────────────────────────────────────────────────────────────┘

File Location Requirements

文件位置要求

⚠️ CRITICAL: The 
fix_plan.json
file MUST ALWAYS be located in:
docs/specs/[ID-feature]/_ralph_loop/fix_plan.json
This is enforced by the script to prevent LLMs from creating files in wrong locations.
Migration: If you have an old 
fix_plan.json
in the root of your spec folder, the script will automatically migrate it to 
_ralph_loop/
on first run.
⚠️ 关键要求：
fix_plan.json
文件必须始终位于：
docs/specs/[ID-feature]/_ralph_loop/fix_plan.json
脚本会强制执行此要求，以防止LLM在错误位置创建文件。
迁移：如果你的规范文件夹根目录中有旧的
fix_plan.json
，脚本会在首次运行时自动将其迁移到
_ralph_loop/
目录下。

Instructions

使用说明

Phase 1: Initialize

阶段1：初始化

Run the Python script with 
--action=start
to scan task files and create 
fix_plan.json
in the correct location:
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041
使用
--action=start
参数运行Python脚本，扫描任务文件并在正确位置创建
fix_plan.json
：
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041

Phase 2: Execute Loop Steps

阶段2：执行循环步骤

Run the script with 
--action=loop
to get the current state and the command to execute:
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
The script will show you the exact command to execute for the current step. Execute it in your CLI, then run the loop command again.
使用
--action=loop
参数运行脚本，获取当前状态和要执行的命令：
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
脚本会展示当前步骤需执行的精确命令。在CLI中执行该命令，然后再次运行loop命令。

Phase 3: Advance State (Manual)

阶段3：手动推进状态

After executing the shown command, manually advance to the next step:
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=next \
  --spec=docs/specs/001-feature/
This updates 
fix_plan.json
to the next state (e.g., 
implementation
→ 
review
).
执行展示的命令后，手动推进到下一步：
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=next \
  --spec=docs/specs/001-feature/
这会将
fix_plan.json
更新到下一状态（例如
implementation
→ 
review
）。

Phase 4: Monitor Progress

阶段4：监控进度

Check status anytime with 
--action=status
:
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/
随时使用
--action=status
参数检查状态：
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

Quick Start

快速开始

1. Initialize

1. 初始化

bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041 \
  --agent=claude
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041 \
  --agent=claude

2. Run Loop

2. 运行循环

bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
The script will show you the command to execute. Run it, then run the loop again.
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
脚本会展示要执行的命令。执行后，再次运行loop。

3. Check Status

3. 检查状态

bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/
bash
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

Arguments

参数说明

ArgumentDescription
--action
start
(init), 
loop
(run one step), 
status
, 
resume
, 
next
(advance step)
--spec
Spec folder path (e.g. 
docs/specs/001-feature/
)
--from-task
Start of task range (e.g. 
TASK-036
)
--to-task
End of task range (e.g. 
TASK-041
)
--agent
Default agent: 
claude
, 
codex
, 
copilot
, 
kimi
, 
gemini
, 
glm4
, 
minimax
--no-commit
Skip git commits (for testing)
参数描述
--action
start
（初始化）、
loop
（运行一个步骤）、
status
、
resume
、
next
（推进步骤）
--spec
规范文件夹路径（例如
docs/specs/001-feature/
）
--from-task
任务范围起始（例如
TASK-036
）
--to-task
任务范围结束（例如
TASK-041
）
--agent
默认Agent：
claude
、
codex
、
copilot
、
kimi
、
gemini
、
glm4
、
minimax
--no-commit
跳过git提交（用于测试）

Step Details

步骤详情

Step 1: Initialize (
--action=start
)

步骤1：初始化（
--action=start
）

The script:
  1. Scans 
    tasks/TASK-*.md
    files in the spec folder
  2. Extracts metadata from YAML frontmatter (id, title, status, lang, dependencies, agent)
  3. Applies 
    --from-task
    and 
    --to-task
    filters
  4. Creates 
    fix_plan.json
    with full state
脚本执行以下操作：
  1. 扫描规范文件夹中的
    tasks/TASK-*.md
    文件
  2. 从YAML前置元数据中提取信息（id、标题、状态、语言、依赖、Agent）
  3. 应用
    --from-task
    和
    --to-task
    过滤器
  4. 创建包含完整状态的
    fix_plan.json

Step 2: Choose Task (
choose_task
)

步骤2：选择任务（
choose_task
）

The script:
  1. Finds pending tasks within range
  2. Checks dependencies are satisfied
  3. Selects next task
  4. Updates 
    fix_plan.json
    with 
    current_task
  5. Shows command to execute
脚本执行以下操作：
  1. 查找范围内的待处理任务
  2. 检查依赖是否已满足
  3. 选择下一个任务
  4. 在
    fix_plan.json
    中更新
    current_task
  5. 展示要执行的命令

Step 3: Implementation (
implementation
)

步骤3：实现（
implementation
）

The script shows:
→ Implementation: TASK-037

Execute:
  /specs:task-implementation --task=TASK-037

After execution, update state:
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/
脚本展示：
→ 实现：TASK-037

执行：
  /specs:task-implementation --task=TASK-037

执行完成后，更新状态：
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

Step 4: Review (
review
)

步骤4：评审（
review
）

The script shows:
→ Review: TASK-037 | Retry: 0/3

Execute:
  /specs:task-review --task=TASK-037

Review the generated review report, then update state:
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/
脚本展示：
→ 评审：TASK-037 | 重试：0/3

执行：
  /specs:task-review --task=TASK-037

评审生成的评审报告后，更新状态：
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

Step 5: Fix (
fix
) - If Review Failed

步骤5：修复（
fix
）- 若评审失败

If issues found, script shows fix instructions. After fixes, user runs loop again.
如果发现问题，脚本会展示修复说明。修复完成后，用户再次运行loop。

Step 6: Cleanup (
cleanup
)

步骤6：清理（
cleanup
）

The script shows:
→ Cleanup: TASK-037

Execute:
  /developer-kit-specs:specs-code-cleanup --task=TASK-037
脚本展示：
→ 清理：TASK-037

执行：
  /developer-kit-specs:specs-code-cleanup --task=TASK-037

Step 7: Sync (
sync
)

步骤7：同步（
sync
）

The script shows:
→ Sync: TASK-037

Execute:
  /specs:spec-sync-with-code docs/specs/001-feature/ --after-task=TASK-037
脚本展示：
→ 同步：TASK-037

执行：
  /specs:spec-sync-with-code docs/specs/001-feature/ --after-task=TASK-037

Step 8: Update Done (
update_done
)

步骤8：标记完成（
update_done
）

The script:
  1. Marks task as completed in 
    fix_plan.json
  2. Commits git changes (unless 
    --no-commit
    )
  3. Updates iteration count
  4. Returns to 
    choose_task
脚本执行以下操作：
  1. 在
    fix_plan.json
    中标记任务为已完成
  2. 提交git变更（除非使用
    --no-commit
    ）
  3. 更新迭代次数
  4. 返回
    choose_task
    状态

Multi-Agent Support

多Agent支持

Default Agent for All Tasks

所有任务使用默认Agent

bash
python3 ralph_loop.py --action=start --spec=... --agent=codex
bash
python3 ralph_loop.py --action=start --spec=... --agent=codex

Per-Task Agent

按任务指定Agent

Specify agent in task file YAML frontmatter:
yaml
---
id: TASK-036
title: Refactor user service
status: pending
lang: java
agent: codex
---
Supported agents: 
claude
, 
codex
, 
copilot
, 
kimi
, 
gemini
, 
glm4
, 
minimax
在任务文件的YAML前置元数据中指定Agent：
yaml
---
id: TASK-036
title: 重构用户服务
status: pending
lang: java
agent: codex
---
支持的Agent：
claude
、
codex
、
copilot
、
kimi
、
gemini
、
glm4
、
minimax

Using with /loop (Claude Code)

与/loop（Claude Code）配合使用

For automatic scheduling every 5 minutes:
bash
/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
This will repeatedly run the loop, showing you the next command each time.
Note: The Ralph Loop is now managed directly through the Python script. The deprecated 
/specs:ralph-loop
command has been removed.
如需每5分钟自动调度：
bash
/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
这会重复运行循环，每次展示下一个命令。
注意：Ralph Loop现在直接通过Python脚本管理。已移除已弃用的
/specs:ralph-loop
命令。

Task File Format

任务文件格式

Each task should be a separate file: 
tasks/TASK-XXX.md
markdown
---
id: TASK-036
title: Implement user authentication
status: pending
lang: java
dependencies: []
complexity: medium
agent: claude
---
每个任务应为独立文件：
tasks/TASK-XXX.md
markdown
---
id: TASK-036
title: 实现用户认证
status: pending
lang: java
dependencies: []
complexity: medium
agent: claude
---

Description

描述

Implement JWT-based authentication for the API.
为API实现基于JWT的认证功能。

Acceptance Criteria

验收标准

  • Login endpoint returns JWT token
  • Token validation middleware
  • Refresh token mechanism
undefined
  • 登录端点返回JWT令牌
  • 令牌验证中间件
  • 刷新令牌机制
undefined

Examples

示例

Example 1: Basic Usage

示例1：基础用法

bash
undefined
bash
undefined

Initialize

初始化

python3 ralph_loop.py --action=start
--spec=docs/specs/001-feature/
--from-task=TASK-001
--to-task=TASK-005
python3 ralph_loop.py --action=start
--spec=docs/specs/001-feature/
--from-task=TASK-001
--to-task=TASK-005

Loop until complete

循环直到完成

while true; do python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

Execute the shown command manually

Then continue loop

done
undefined
while true; do python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

手动执行展示的命令

然后继续循环

done
undefined

Example 2: With Claude Code /loop

示例2：配合Claude Code /loop

bash
undefined
bash
undefined

Start with specific range

从指定范围开始

/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py
--action=loop
--spec=docs/specs/002-tdd-command
--from-task=TASK-001
--to-task=TASK-010
undefined
/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py
--action=loop
--spec=docs/specs/002-tdd-command
--from-task=TASK-001
--to-task=TASK-010
undefined

Example 3: Multi-Agent Setup

示例3：多Agent配置

bash
undefined
bash
undefined

Initialize with Claude as default

使用Claude作为默认Agent初始化

python3 ralph_loop.py --action=start
--spec=docs/specs/001-feature/
--agent=claude
python3 ralph_loop.py --action=start
--spec=docs/specs/001-feature/
--agent=claude

Some tasks have "agent: codex" in their frontmatter

部分任务的前置元数据中包含"agent: codex"

Those will show Codex-formatted commands

这些任务会展示Codex格式的命令

undefined
undefined

Best Practices

最佳实践

  • One step per invocation: Execute exactly one step, save state, stop
  • Trust the state: Read from 
    fix_plan.json
    , write to 
    fix_plan.json
  • No context accumulation: State lives in the file, not in context
  • Manual command execution: The script shows commands; you execute them in your CLI
  • Retry on review failure: Max 3 retries before failing
  • Range filtering: Always filter by 
    task_range
  • Dependencies first: Only pick tasks where all dependencies are done
  • Git commits: The script auto-commits after each completed task
  • 每次调用一个步骤：仅执行一个步骤，保存状态后停止
  • 信任状态文件：从
    fix_plan.json
    读取状态，写入状态到
    fix_plan.json
  • 避免上下文累积：状态存储在文件中，而非上下文里
  • 手动执行命令：脚本展示命令，由你在CLI中执行
  • 评审失败时重试：最多重试3次，之后标记失败
  • 范围过滤：始终使用
    task_range
    进行过滤
  • 优先处理依赖：仅选择所有依赖已完成的任务
  • Git提交：脚本会在每个任务完成后自动提交

Constraints and Warnings

约束与警告

  • Context explosion: Do NOT implement + review + sync in one invocation — context will overflow
  • Max retries: Review failures retry up to 3 times, then fail
  • Git state: Ensure clean git state before starting
  • Test infrastructure: Loop requires tests to pass — without tests, backpressure is ineffective
  • Strict state validation: Valid 
    state.step
    values are ONLY: 
    init
    , 
    choose_task
    , 
    implementation
    , 
    review
    , 
    fix
    , 
    cleanup
    , 
    sync
    , 
    update_done
    , 
    complete
    , 
    failed
  • NO automatic command execution: The script shows commands but does NOT execute them — you must run them in your CLI
  • 上下文溢出：请勿在一次调用中同时完成实现、评审和同步——否则会导致上下文窗口溢出
  • 最大重试次数：评审失败最多重试3次，之后标记失败
  • Git状态：开始前确保Git状态干净
  • 测试基础设施：循环要求测试通过——没有测试的话，反向压力机制无效
  • 严格状态验证：有效的
    state.step
    值仅包括：
    init
    、
    choose_task
    、
    implementation
    、
    review
    、
    fix
    、
    cleanup
    、
    sync
    、
    update_done
    、
    complete
    、
    failed
  • 禁止自动执行命令：脚本仅展示命令，不会自动执行——你必须在CLI中运行它们

Troubleshooting

故障排除

"fix_plan.json not found"

"fix_plan.json not found"

Run 
--action=start
first:
bash
python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/
The script will create 
fix_plan.json
in the correct location:
docs/specs/001-feature/_ralph_loop/fix_plan.json
先运行
--action=start
：
bash
python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/
脚本会在正确位置创建
fix_plan.json
：
docs/specs/001-feature/_ralph_loop/fix_plan.json

"fix_plan.json in wrong location"

"fix_plan.json in wrong location"

If you see a warning about the file being in the wrong location, the script will guide you through migration:
bash
undefined
如果看到文件位置错误的警告，脚本会引导你完成迁移：
bash
undefined

Manual migration if needed

如需手动迁移

mkdir -p docs/specs/001-feature/_ralph_loop mv docs/specs/001-feature/fix_plan.json docs/specs/001-feature/_ralph_loop/fix_plan.json

The script will automatically migrate old files on first run.
mkdir -p docs/specs/001-feature/_ralph_loop mv docs/specs/001-feature/fix_plan.json docs/specs/001-feature/_ralph_loop/fix_plan.json

脚本会在首次运行时自动迁移旧文件。

"Invalid spec folder"

"Invalid spec folder"

Run 
--action=start
first:
bash
python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/
先运行
--action=start
：
bash
python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/

Task files not found

未找到任务文件

Ensure tasks are in 
tasks/TASK-XXX.md
format with YAML frontmatter.
确保任务文件为
tasks/TASK-XXX.md
格式，且包含YAML前置元数据。

Wrong agent commands

Agent命令错误

Check 
--agent
parameter or task 
agent:
frontmatter field.
检查
--agent
参数或任务文件中的
agent:
前置元数据字段。

References

参考资料

  • references/state-machine.md
    - Complete state machine documentation
  • references/multi-cli-integration.md
    - Multi-CLI setup guide
  • references/loop-prompt-template.md
    - Prompt template for shell loops
  • references/state-machine.md
    - 完整状态机文档
  • references/multi-cli-integration.md
    - 多CLI设置指南
  • references/loop-prompt-template.md
    - Shell循环的提示模板