Task Loop

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:

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.

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.

Loop Protocol Template

Core protocol for PROMPT.md generation. Adapt this template to the specific backlog — don't copy verbatim. Each backlog has different verification needs, reference material, and dependency structures.

Template

# Prompt

You are running in an automated loop. Read these files before doing anything else:

1. `TASKS/<name>/loop-state.md` — current task and progress
2. `TASKS/<name>/run-log.md` — what previous iterations completed
3. `TASKS/<name>/backlog.md` — the full task list

## Protocol

**If loop-state.md doesn't exist or status is `done`:**

- Append a run-log entry for the completed task (if any)
- If no unchecked `[ ]` tasks remain in backlog.md, print `__PROMISE_RL_DONE__`
  on its own final line and exit
- Pick the next unchecked `[ ]` task from backlog.md
- Create/update loop-state.md with `status: in_progress`

**If status is `in_progress` or `verifying`:**

- Resume from the checklist — don't restart the task

**If status is `blocked`:**

- Append to run-log.md with the blocker
- Move to `next_task`, update loop-state.md

## Verification

<Adapt this section based on the backlog's verification patterns.
Include global rules and reference external docs where appropriate.>

## Completion rule

Only set `status: done` when ALL are true:

- Code changes committed
- Verification passed (per rules above)
- Backlog checkbox updated to `[x]`
- loop-state.md updated with commit SHA

## Surprises

Record in loop-state.md. If durable, update code comments or docs.

Run the outer loop with rl -- ... so the default promise-token handling stops the shell runner once the backlog is exhausted. In Ralph-loop terms this token is the completion promise. Use --promise-token to override the token or --no-promise-token to disable this behaviour for a specific run.

Adaptation Points

When generating PROMPT.md from this template, adapt these sections:

File paths

Replace <name> with the actual directory name.

Protocol — dependency handling

If the backlog has a dependency graph, add to the "pick next task" step:

- If no unchecked `[ ]` tasks remain after applying the dependency rules,
  print `__PROMISE_RL_DONE__` on its own final line and exit
- Pick the next unchecked `[ ]` task from backlog.md, respecting the
  dependency graph — skip tasks whose dependencies aren't complete

Verification

Extract verification rules from the backlog. Sources:

1. Global "How to Use" section — if the backlog has a global verification workflow, summarise it here 2. Per-task verification — if tasks have different verification needs, add a "minimum per change type" table 3. Referenced docs — if the backlog references external docs (e.g. docs/figma-workflow.md), add them here

Example adaptation for a Figma-based backlog:

## Verification

Follow `docs/figma-workflow.md` for visual validation (steps 3-5).

Minimum per change type:

- Seed/content: `pnpm test` + `pnpm typecheck` + visual check
- Block schema: `pnpm generate:types` + `pnpm test` + `pnpm typecheck`
- Component/layout: `pnpm test` + `pnpm typecheck` + Storybook screenshots at 1440px and 375px

Example adaptation for a PRD-based backlog:

## Verification

Run the project's test suite after every change. Minimum per task type:

- Schema/model changes: generate types + run tests + run migrations
- API changes: run tests + verify endpoint manually
- UI changes: run tests + screenshot at key breakpoints
- Config changes: run build to verify no errors

Reference material

If the user mentioned helpful docs or skills, add a section:

## Reference

These docs and skills are relevant to executing tasks in this backlog:

- `docs/figma-workflow.md` — visual validation workflow
- `docs/testing.md` — test architecture and patterns