Ralph Loop
Run a spec-backed task loop where your agent implements, reviews, and syncs each TASK file in order until the whole feature is done.
Overview
Ralph Loop is an agent skill most often used in Build (also Ship) that runs a spec-backed task loop with implement, review, and sync steps per TASK file.
Install
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill ralph-loopWhat is this skill?
- Tracks spec path, tasks file, and current task index in structured loop state
- Per-task pipeline: implement → review → sync with explicit step status
- TASK dependencies (e.g. TASK-002 after TASK-001) gate what runs next
- Machine states: pending, in_review, completed, plus loop-level review state
- Aligns agent work to docs/specs/…/tasks/TASK-NNN.md files on disk
- Three-step per-task pipeline: implement, review, sync
- Example specs layout under docs/specs/001-example-new-spec/ with TASK-001 through TASK-004
Adoption & trust: 710 installs on skills.sh; 271 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have specs and TASK markdown files but your agent jumps around, skips review, or loses track of which task is active.
Who is it for?
Solo builders executing a written spec with TASK-001…N files and wanting gated implement/review/sync discipline.
Skip if: Greenfield ideas with no spec or tasks tree, or one-off edits that do not need a multi-task loop state file.
When should I use this skill?
You have a spec directory and tasks markdown tree and want the agent to execute tasks in dependency order with implement/review/sync gates.
What do I get? / Deliverables
Each task moves through implement, review, and sync with dependency-aware ordering until the spec’s task list is completed and loop state reflects review-ready progress.
- Updated per-task step status (implement/review/sync)
- Completed task files aligned to the spec
- Loop state reflecting current task and review readiness
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because Ralph Loop drives ordered implementation against spec and per-task markdown artifacts. PM subphase fits spec directories, tasks indexes, dependency ordering, and per-task status (implement/review/sync).
Where it fits
Break an approved feature brief into TASK files under docs/specs before the first implement pass.
Advance currentTaskIndex only after implement and review steps mark done for the active TASK.
Hold loop state in review until sync completes on the task under in_review.
Re-open the loop on a new spec folder for the next incremental feature tranche.
How it compares
Use instead of ad-hoc “keep coding” loops when you already have spec + tasks artifacts to honor.
Common Questions / FAQ
Who is ralph-loop for?
Indie builders and small teams using agentic coding with docs/specs task files who need structured progression through implement, review, and sync.
When should I use ralph-loop?
During Build when turning a scoped spec into code task-by-task, and during Ship when review/sync gates must complete before the next TASK; also when resuming a half-finished task index from saved loop state.
Is ralph-loop safe to install?
Review the Security Audits panel on this Prism page and inspect the developer-kit repo before granting filesystem and git access to your spec and source tree.
SKILL.md
READMESKILL.md - Ralph Loop
{ "spec": "docs/specs/001-example-new-spec/", "specFile": "docs/specs/001-example-new-spec/2026-04-02--try-new-ralph-loop-skill.md", "tasksFile": "docs/specs/001-example-new-spec/2026-04-02--try-new-ralph-loop-skill--tasks.md", "initialized": "2026-04-02", "currentTaskIndex": 1, "state": "review", "tasks": [ { "id": "TASK-001", "title": "Try New Ralph Loop Skill Task 001", "file": "docs/specs/001-example-new-spec/tasks/TASK-001.md", "dependencies": [], "status": "completed", "steps": { "implement": "done", "review": "done", "sync": "done" } }, { "id": "TASK-002", "title": "Try New Ralph Loop Skill Task 002", "file": "docs/specs/001-example-new-spec/tasks/TASK-002.md", "dependencies": [ "TASK-001" ], "status": "in_review", "steps": { "implement": "done", "review": "pending", "sync": "pending" } }, { "id": "TASK-003", "title": "Try New Ralph Loop Skill Task 003", "file": "docs/specs/001-example-new-spec/tasks/TASK-003.md", "dependencies": [ "TASK-002" ], "status": "pending", "steps": { "implement": "pending", "review": "pending", "sync": "pending" } }, { "id": "TASK-004", "title": "Try New Ralph Loop Skill Task 004", "file": "docs/specs/001-example-new-spec/tasks/TASK-004.md", "dependencies": [ "TASK-003" ], "status": "pending", "steps": { "implement": "pending", "review": "pending", "sync": "pending" } }, { "id": "TASK-005", "title": "Try New Ralph Loop Skill Task 005", "file": "docs/specs/001-example-new-spec/tasks/TASK-005.md", "dependencies": [], "status": "pending", "steps": { "implement": "pending", "review": "pending", "sync": "pending" } } ], "lastUpdated": "2026-04-02T14:08:44Z" } # Ralph Loop Prompt Template — One Step Per Invocation This template generates `prompt.md` for the shell loop approach. **One invocation = one step.** The LLM reads state, executes one step, updates state, and stops. Generated by `/developer-kit-specs:specs.ralph-loop --action=start`. ## Template ``` 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] ``` --- ## Step: init ``` 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" ``` --- ## Step: choose_task ``` 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" ``` --- ## Step: implementation ``` 1. Read fix_plan.json to get current_task and curr