Ralph Loop Prompt Template — One Step Per Invocation

Ralph Loop State Machine — One Step Per Invocation
================================================
Read fix_plan.json → Execute current step → Update state → Stop

DO NOT execute multiple steps. One step only.

Current State:
- Step: CURRENT_STEP
- Task: CURRENT_TASK (or "none")
- Range: FROM_TASK → TO_TASK
- Iteration: ITERATION_NUM
- Retry count: RETRY_COUNT (for review failures)

Execute Step: CURRENT_STEP
==========================
[Step-specific instructions below]

1. Read all task files from SPEC_FOLDER/tasks/TASK-*.md
2. Extract from YAML frontmatter: id, title, status, lang, dependencies, complexity
3. Parse --from-task and --to-task to set task_range
4. Filter tasks by range: exclude tasks with number < from_num or > to_num
5. Set state.step = "choose_task"
6. Save fix_plan.json
7. Print: "Initialized | Range: TASK-036→TASK-041 | Tasks in range: N"

1. Read fix_plan.json
2. Filter pending tasks to only those within task_range
3. Filter to tasks where all dependencies are in done array
4. Sort by priority (lower complexity_score = higher priority)
5. If no tasks remain:
   - Set state.step = "complete"
   - Save and print completion summary
6. Else:
   - Pick first task (most important)
   - Set state.current_task = TASK-ID
   - Set state.current_task_file = task file path
   - Set state.current_task_lang = lang
   - Set state.step = "implementation"
   - Set state.retry_count = 0
7. Save fix_plan.json
8. Print: "Chosen: TASK-ID [title] | Next: implementation"

1. Read fix_plan.json to get current_task and current_task_file
2. Read the task file CURRENT_TASK_FILE
3. Run task-implementation:
   /developer-kit-specs:specs.task-implementation --lang=LANG --task="TASK_FILE"
4. If implementation succeeds:
   - Set state.step = "review"
5. If implementation fails:
   - Set state.step = "failed"
   - Set state.error = "implementation failed"
6. Save fix_plan.json
7. Print: "Implementation: TASK-ID | Success → review | Failure → failed"

1. Read fix_plan.json to get current_task and current_task_file
2. Run task-review with --no-confirm:
   /developer-kit-specs:specs.task-review --no-confirm --lang=LANG "TASK_FILE"
3. Read the review report TASK-FILE--review.md
4. If review passes (all criteria met, no issues):
   - Set state.step = "cleanup"
5. If review fails (issues found):
   - Increment state.retry_count
   - If retry_count >= 3:
     - Set state.step = "failed"
     - Set state.error = "review failed after 3 retries"
   - Else:
     - Set state.step = "fix"
6. Save fix_plan.json
7. Print: "Review: TASK-ID | Clean → cleanup | Issues → fix (retry N/3)"

1. Read fix_plan.json to get current_task and current_task_file
2. Run code-cleanup with --no-confirm:
   /developer-kit-specs:specs-code-cleanup --no-confirm --lang=LANG --task="TASK_FILE"
3. Set state.step = "sync"
4. Save fix_plan.json
5. Print: "Cleanup: TASK-ID complete | Next: sync"

1. Read fix_plan.json to get current_task
2. Read the review report: docs/specs/[id]/tasks/TASK-XXX--review.md
3. Fix the reported issues:
   - Run /developer-kit-specs:specs.task-implementation --lang=LANG --task="TASK_FILE"
   - Or manually apply edits to address findings
4. If fixes succeed:
   - Set state.step = "review"
5. If fixes fail:
   - Set state.step = "failed"
   - Set state.error = "fix failed"
6. Save fix_plan.json
7. Print: "Fix: TASK-ID applied | Next: review"

1. Read fix_plan.json to get current_task and spec_folder
2. Run spec-sync-with-code:
   /developer-kit-specs:specs.spec-sync-with-code SPEC_FOLDER/ --after-task=TASK-ID
3. Set state.step = "update_done"
4. Save fix_plan.json
5. Print: "Sync: TASK-ID complete | Next: update_done"

1. Read fix_plan.json to get current_task
2. Update the task's YAML frontmatter:
   - status: completed
   - completed_date: YYYY-MM-DD
3. In fix_plan.json:
   - Move TASK-ID from pending[] to done[]
   - Increment state.iteration
   - Increment state.range_progress.done_in_range
   - Update state.last_updated
   - For each remaining pending task: check if all dependencies are in done[], if yes set dependencies_satisfied = true
4. Set state.step = "choose_task"
5. Save fix_plan.json
6. Print: "Done: TASK-ID | Progress: N/M in range (P%) | Next: choose_task"

Ralph Loop COMPLETE
=====================
Task Range: FROM_TASK → TO_TASK
Tasks Completed: N/N
Total Iterations: ITERATION_NUM
Deviations Detected: N

All tasks in range implemented and verified.
Run --action=start with a new range to continue.

Ralph Loop FAILED
==================
Task: CURRENT_TASK
Error: ERROR_MESSAGE
Retry count: RETRY_COUNT/3

Fix the issues manually, then resume:
/developer-kit-specs:specs.ralph-loop --action=loop --spec=SPEC_FOLDER/