Recursive Handoff

Run the same prompt repeatedly with fresh context until a finish condition is met.

When to Use

• Long-running tasks that would exhaust context
• Repetitive operations (process items one by one, migrate in batches)
• Polling/waiting for external state changes
• Any task where "keep doing X until Y" applies

Required Parameters

1. Finish Condition

You MUST get a finish condition from the user before starting.

The condition must be verifiable programmatically (file check, command output, grep result, API response, etc.)

Examples:

• "All files in src/legacy/ have been processed"
• "No more TODO comments exist in the codebase"
• "The API returns status 200"
• "The queue is empty"

2. Hard Limit (default: 20)

Maximum iterations before stopping. Prevents runaway loops.

How It Works

┌─────────────────────────────────────────┐
│  Thread 1: Check condition → not met    │
│            Do work → handoff            │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│  Thread 2: Check condition → not met    │
│            Do work → handoff            │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│  Thread 3: Check condition → MET        │
│            STOP (no handoff)            │
└─────────────────────────────────────────┘

Each iteration:

1. Check iteration count - stop if limit reached
2. Check finish condition
3. If met → stop, report completion
4. If not met → do one unit of work → handoff to continue

The Handoff Prompt Template

RECURSIVE TASK - Iteration [N] of [LIMIT]

## Finish Condition
[CONDITION]

## How to Check
[COMMAND OR METHOD TO VERIFY CONDITION]

## If Limit Reached or Condition Met
Stop. Report: "✅ Complete: [summary]" or "⚠️ Limit reached after [N] iterations"
Do NOT handoff.

## If Condition NOT Met

### Task
[WHAT TO DO THIS ITERATION]

### After Completing Work
Handoff with follow: true, incrementing iteration count:

[PASTE THIS PROMPT WITH N+1]

Example: Generic Processing Loop

User: "Process all items in the queue"

Finish condition: Queue is empty

Handoff prompt:

RECURSIVE TASK - Iteration 1 of 20

## Finish Condition
Queue is empty

## How to Check
[command to check queue length]
If result is 0, condition is met.

## If Limit Reached or Condition Met
Stop. Report completion status.
Do NOT handoff.

## If Condition NOT Met

### Task
1. Get next item from queue
2. Process it
3. Remove from queue

### After Completing Work
Handoff with follow: true, goal:

[THIS PROMPT WITH ITERATION 2 of 20]

Starting the Loop

Once setup is complete, invoke handoff with follow: true:

handoff
  goal: [THE FULL HANDOFF PROMPT]
  follow: true

The loop continues autonomously until finish condition is met or limit is reached.