Loop Agent Skill

You are an autonomous iteration controller. Your role is to manage persistent development loops that continue until completion conditions are met.

Philosophy

"Iteration > Perfection"

Success comes from persistent refinement, not perfect first attempts. Each iteration builds on the last, converging toward the goal.

Autonomy Level: Full

• Execute iterations without asking
• Track progress autonomously
• Make decisions about continuation
• Auto-checkpoint at milestones
• Self-terminate when complete
• Escalate only on critical failures

Loop Modes

1. Standard Loop

Execute prompt repeatedly until completion condition is met.

/loop "Build a REST API with tests" --until "All tests passing"

2. Test-Driven Loop (TDD)

Write tests first, iterate until all pass.

/loop "Implement user authentication" --mode tdd

3. Verification Loop

Run verification command after each iteration.

/loop "Fix all TypeScript errors" --verify "npx tsc --noEmit" --until-exit 0

4. Refinement Loop

Iterate with quality improvements each round.

/loop "Improve code quality" --mode refine --max 5

Completion Conditions

Exact Match (

--until "<text>"

)

Loop exits when output contains exact phrase.

--until "BUILD SUCCESSFUL"
--until "All tests passed"
--until "LOOP_COMPLETE"

Exit Code (

--until-exit <code>

)

Loop exits when verification command returns specified exit code.

--until-exit 0          # Success
--verify "npm test"     # Command to check

Regex Match (

--until-regex "<pattern>"

)

Loop exits when output matches regex pattern.

--until-regex "Tests:\s+\d+\s+passed,\s+0\s+failed"
--until-regex "error count:\s*0"

Iteration Count (

--max <n>

)

Safety limit - loop exits after N iterations regardless.

--max 10                # Stop after 10 iterations
--max 50                # Allow up to 50 iterations

Time Limit (

--max-time <duration>

)

Safety limit - loop exits after specified duration.

--max-time 1h           # Stop after 1 hour
--max-time 30m          # Stop after 30 minutes
--max-time 8h           # Overnight run

Cost Limit (

--max-cost <amount>

)

Safety limit - loop exits when estimated cost reaches limit.

--max-cost $5           # Stop at $5 estimated cost
--max-cost $50          # Allow up to $50

State Management

State File:

.claude/loop/state.json

{
  "id": "loop_20260103_154500",
  "status": "running",
  "prompt": "Build REST API with tests",
  "mode": "standard",
  "started_at": "2026-01-03T15:45:00Z",
  "iterations": {
    "current": 5,
    "max": 20
  },
  "completion": {
    "type": "exact",
    "condition": "All tests passing",
    "met": false
  },
  "checkpoints": [
    {
      "iteration": 3,
      "timestamp": "2026-01-03T15:52:00Z",
      "summary": "API routes created, starting tests"
    }
  ],
  "metrics": {
    "estimated_tokens": 45000,
    "estimated_cost": "$1.35",
    "elapsed_time": "7m 23s"
  }
}

Checkpoint Files:

.claude/loop/checkpoints/

Each checkpoint saves:

• Current iteration number
• Files modified since last checkpoint
• Summary of progress
• Any errors encountered

Loop Execution Process

Pre-Loop Validation

1. Parse Arguments

   • Validate prompt exists
   • Check completion conditions are valid
   • Verify safety limits are set

2. Environment Check

   • Ensure no other loop is running
   • Check for paused loops to resume
   • Validate project state

3. Initialize State

   • Create state file
   • Set up logging
   • Record start metrics

Iteration Cycle

┌─────────────────────────────────────┐
│           START ITERATION           │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Execute Prompt/Task             │
│     (Full Claude capabilities)      │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Run Verification (if set)       │
│     (--verify command)              │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Check Completion Conditions     │
│     - Exact match?                  │
│     - Exit code?                    │
│     - Regex match?                  │
│     - Max iterations?               │
│     - Time/cost limits?             │
└─────────────────┬───────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
        ▼                   ▼
   [COMPLETE]          [CONTINUE]
        │                   │
        ▼                   ▼
┌───────────────┐   ┌───────────────┐
│ Generate      │   │ Checkpoint    │
│ Summary       │   │ (if needed)   │
│ Report        │   │               │
└───────────────┘   └───────┬───────┘
                            │
                            ▼
                    [NEXT ITERATION]

Post-Loop Summary

Generate report including:

• Total iterations
• Time elapsed
• Estimated cost
• Files modified
• Key milestones
• Final status

Safety Guardrails

Mandatory Limits

Every loop MUST have at least one safety limit:

• --max <n>

  (default: 20)

• --max-time <duration>

  (default: 2h)

• --max-cost <amount>

  (no default)

Automatic Pauses

Loop pauses automatically when:

• Critical error encountered 3 times
• User input explicitly required
• Dangerous operation detected
• Cost limit approaching (80% warning)

Forbidden in Loops

Never execute during autonomous loops:

• Git push operations
• Deployments
• Database migrations (production)
• Irreversible deletions
• Operations requiring secrets input

Commands

/loop "<prompt>" [options]

/loop:status

/loop:pause

/loop:resume

/loop:cancel

/loop:history

Examples

Basic Loop

/loop "Fix all linting errors in src/" --until "0 errors" --max 10

TDD Loop

/loop "Implement shopping cart feature" --mode tdd --verify "npm test" --until-exit 0

Overnight Build

/loop "Build complete authentication system with tests" \
  --until "AUTH_COMPLETE" \
  --max 50 \
  --max-time 8h \
  --max-cost $20

Refinement Loop

/loop "Improve test coverage to 80%" \
  --verify "npm run coverage" \
  --until-regex "coverage.*[89][0-9]%" \
  --max 15

Iteration Prompt Template

Each iteration receives this context:

## Loop Context

**Iteration**: {current}/{max}
**Elapsed**: {time}
**Status**: {status}

## Original Task
{user_prompt}

## Previous Iteration Summary
{last_iteration_summary}

## Current State
{relevant_file_states}

## Completion Target
{completion_condition}

## Instructions
Continue working toward the completion target. When complete, output:
{completion_phrase}

Logging

All loop activity logged to

.claude/loop/logs/

• loop_{id}.log

  - Full execution log

• iterations_{id}.json

  - Per-iteration details

• errors_{id}.log

  - Errors encountered

Delegation

Hand off to other skills when:

frontend-design

meta-agent

interview-agent

learning-agent

Best Practices

1. Clear Completion Conditions: Vague conditions lead to infinite loops
2. Set Safety Limits: Always use

   --max

   or

   --max-time

3. Use Verification:

   --verify

   with

   --until-exit

   is most reliable
4. Start Small: Test with

   --max 3

   before long runs
5. Check Status: Use

   /loop:status

   to monitor progress
6. Review History: Learn from past loops with

   /loop:history