📝 The Prompt That Triggers the Loop
The starting point for any task runner is the prompt that loads Claude Code's loop capability. With a single line, the agent knows how to set up the loop system, iterate through tasks, and schedule itself again.
📋 Ready-to-Use Prompt (copy and use)
Load the loop skill, work through plan.md one task at a timeThis prompt does three things: loads the "loop skill" (a native Claude Code capability), points to the plan.md file as the source of tasks, and instructs the agent to process one task per cycle.
"Sei que este é um exemplo muito, muito básico, mas quero manter tudo simples de propósito. Mas ele escreveu o prompt: /loop work through plan.md one task at a time."
⚙ What Happens Internally
Claude Code loads the loop skill as its first action: "it loads the loop skill as the very first thing"
Identifies that plan.md contains a sequential task list
Automatically configures /loop and schedules the first wake-up
The agent writes the loop prompt itself: “/loop work through plan.md one task at a time”
📋 plan.md Template
The plan.md is the contract between you and the loop. Each task must be specific, verifiable, and independent. Vague tasks produce vague results. Interdependent tasks break the loop's isolation.
📄 Template (copy and adapt)
# Plan - [Nome do Projeto]
## Tasks
- [ ] **Task 1: Setup inicial**
Criar a estrutura de diretorios e arquivos base.
Criterio: diretorios existem, arquivos criados sem erros.
- [ ] **Task 2: Implementar componente X**
Criar o componente principal com props tipadas.
Criterio: componente renderiza sem erros, tipos corretos.
- [ ] **Task 3: Adicionar estilos**
Aplicar Tailwind CSS seguindo o design system.
Criterio: visual consistente, responsivo em mobile.
- [ ] **Task 4: Escrever testes**
Testes unitarios para cada funcao publica.
Criterio: todos os testes passam, coverage > 80%.
- [ ] **Task 5: Documentacao**
README com instrucoes de uso e exemplos.
Criterio: novo dev consegue rodar seguindo o README.✓ Best Practices
- ✓One task per checkbox
- ✓Explicit acceptance criteria
- ✓Tasks that are independent of each other
- ✓Logical execution order
✗ Anti-Patterns
- ✗"Make the app work" (too vague)
- ✗10+ tasks (excessive fragmentation)
- ✗Tasks that depend on external input
- ✗No "done" criteria
🔍 Monitoring Progress
After you start the loop, the agent works autonomously. Each cycle follows the same pattern: wake up, check the next task, execute, validate, and schedule the next wake-up. You can monitor it directly in the terminal.
"It says this is a sequential list of tasks: it’ll run the first one and then schedule a short wake-up. So it sets up /loop itself."
📊 The Cycle of a Wake-up
Wake-up
The /loop wakes the agent with the prompt it wrote itself
Check plan.md
Reads the file, identifies the next unmarked task
Execute task
Implements, generates files, runs necessary commands
Validate and mark
Checks the acceptance criterion, marks [x] in plan.md, schedules the next wake-up
"It’s resuming with a /loop wake-up. And look, I didn’t write that prompt."
⚙ Configuring Exit Conditions
A loop without an exit condition is the costliest mistake you can make. The agent will run indefinitely, spending tokens without converging on a result. Always define when the loop should stop.
🛑 Three Ways to Stop
1. Natural completion
All tasks in plan.md marked as [x].
/goal All tasks in plan.md are checked off2. Max iterations
Safety net: stop after N cycles, regardless of state.
/loop --max-iterations 10 work through plan.md one task at a time3. Failure condition
If a task fails 3 times, stop and report it.
If a task fails validation 3 times, stop the loop and report what went wrong.🎯 Reflection Point
The safest exit condition is a combination of /goal (natural completion) + max iterations (safety net). That way, if something goes wrong and the agent can’t finish, it stops instead of burning tokens indefinitely.
🔄 Prompt Variations
The basic prompt works for simple task lists, but different scenarios call for variations. Here are prompts adapted for the most common use cases.
Load the loop skill. Work through refactor-plan.md one file at a time.
For each file: refactor, run tests, commit if green. Skip if tests fail after 2 retries.Ideal for incremental refactoring with a test safety net.
Load the loop skill. Work through migration-plan.md one step at a time.
After each step, validate by running the app and checking for errors.
Never proceed to the next step if the current one has errors.For version or framework migrations with rigorous validation.
Load the loop skill. Work through docs-plan.md one section at a time.
For each section: read the source code, write documentation, include code examples.
Mark the task done when the doc file is created and has at least 200 words.Generating documentation from source code.
❓ Questions
Before using the task runner for everything, it’s worth raising the questions Cole Medin himself asks about the basic approach.
Does the simple loop scale?
For 5 tasks, it works. For 50, the context window will explode. Cole Medin notes that "if you loop for a while, you're going to completely bloat your context for your LLM and overwhelm it." The simple task runner has a natural scaling limit.
Quality vs. speed
The loop executes quickly, but without human review between tasks. For PoCs and exploration, that's acceptable. For production code, Cole is direct: “there is no way you're gonna convince me that loop engineering is the way to get the best results possible.”
Cost of a basic loop
Even the simplest loop accumulates tokens quickly. Each wake-up reloads the context. For 5 tasks with validation, expect to spend between 50k and 200k tokens depending on complexity.
🎯 Reflection Point
The task runner is the entry point. Start here, understand the mechanism, and when you need more control, move on to module 4.2 (orchestrator + workers). The progression is deliberate: simple first, complex when needed.
📋 Module Summary
Next Module:
4.2 -- Intermediate Loop: GitHub Issue Bot (orchestrator + parallel workers)