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.

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.

Process

1. Locate the backlog

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.

2. Read and understand the backlog

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.

3. Ask about execution context

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)

4. Generate the loop directory

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:

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).

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:

## <ISO-timestamp> | <task-id> | <done|blocked>
- **Commit:** <sha>
- **Verification:** <what was run>
- **Surprises:** <anything unexpected, or "none">

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.

5. Present the output

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 anatomy

Every generated PROMPT.md has these sections:

Heading — # Prompt
Preamble — "You are running in an automated loop. Read these files before doing anything else:" followed by the three file paths
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
Verification — rules adapted from the backlog, referencing external docs where appropriate
Completion rule — the four conditions that must all be true before marking a task done
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.

loop-state.md

Created at runtime by the agent, not pre-created by this skill. The agent creates it when claiming a task. Format:

---
current_task: <task-id>
status: in_progress | verifying | done | blocked
last_commit: ""
next_task: <task-id>
blockers: ""
---

## Checklist

- [ ] Code changes made
- [ ] Verification passed
- [ ] Backlog checkbox updated
- [ ] Commit created

## Surprises

- (none yet)

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

task-loop