successor-handoff

Successor Handoff

A pattern for running many-hour autonomous workflows without hitting a single context window.

Three rules, one parent, many successor hops. The parent never fills up because it reads only status files. Each track's subagent stays lean via file-first discipline. When a subagent's context does start to swell, a fresh successor spawns in seconds with the filesystem as its memory — no human in the loop, no narrative compression.

The Problem

Autonomous workflows that need many hours of wall-clock time — overnight research, multi-track experiments, 10-hour BigQuery exploration — cannot fit in a single Claude context window. Two naive patterns exist, and both fail:

1. Work until context fills, then session-handoff to a human, then resume. Costs minutes-to-hours per round-trip. Requires a human at an unpredictable time. Each handoff is a lossy narrative compression.
2. Keep one giant context alive. Claude degrades before it errors. Tool outputs that never get pruned clog the prompt. Quality drops quietly.

The pattern in this skill replaces both. The parent orchestrator is permanently lean (reads only status files, never query outputs), so it isn't the thing filling up. Each track is a subagent using disk as memory (per planning-with-files). When a subagent does get stretched, a fresh successor is dispatched in seconds with a resume prompt pointing at the state directory. No human needed. No narrative summary needed. The file system is the knowledge.

When to Use

digraph when {
  "Autonomous work that may exceed one context window?" [shape=diamond];
  "Agent-to-agent handoff mid-run?" [shape=diamond];
  "End-of-run delivery to a human?" [shape=diamond];
  "successor-handoff (this skill)" [shape=box, style=filled, fillcolor=lightyellow];
  "session-handoff" [shape=box];
  "Normal conversation — no handoff pattern" [shape=box];

  "Autonomous work that may exceed one context window?" -> "Agent-to-agent handoff mid-run?" [label="yes"];
  "Autonomous work that may exceed one context window?" -> "Normal conversation — no handoff pattern" [label="no"];
  "Agent-to-agent handoff mid-run?" -> "successor-handoff (this skill)" [label="yes"];
  "Agent-to-agent handoff mid-run?" -> "End-of-run delivery to a human?" [label="no"];
  "End-of-run delivery to a human?" -> "session-handoff" [label="yes"];
  "End-of-run delivery to a human?" -> "Normal conversation — no handoff pattern" [label="no"];
}