# Task Loop > Scaffolds a loop directory for automated agent task execution. Use when asked to "create a task loop", "set up a loop", "scaffold a loop directory", "prepare tasks for rl", or "set up automated execution" for a backlog. Takes an existing backlog and generates PROMPT.md (loop contract), run-log.md (execution history), and .gitignore for ephemeral loop-state.md. - Skill: `connorads/task-loop` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add connorads/task-loop` - Raw SKILL.md: https://api.skillmd.com/api/skills/connorads/task-loop/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: connorads (https://skillmd.com/u/connorads) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/connorads/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//` directory, generate files alongside it. If not, ask where to create the directory or suggest `TASKS//` 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](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: ```markdown ## | | - **Commit:** - **Verification:** - **Surprises:** ``` #### 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 -t 30m -- cys "Read and follow TASKS//PROMPT.md"` Use `cys` (claude yolo stream: skip-permissions + `-p` baked in), not bare `claude -p` - interactive-permission claude stalls the loop the first time it hits a permission prompt with nobody watching. ## 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 loop state machine; the canonical version lives in [references/loop-protocol.md](references/loop-protocol.md) 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](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: ```markdown --- current_task: status: in_progress | verifying | done | blocked last_commit: "" next_task: 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.