Plans

A Plan is how askTheodor tackles something too big for a single Task. It’s a bundle of tasks wired together with dependencies — “do these first, then this, then that” — that the app advances on its own once you’ve approved it.

Plans are the orchestrator’s tool. Hand Theodor a meaty request (“plan and draft our product launch”) and he can propose a Plan: a set of tasks, each assigned to the right worker, with the right order baked in. You review it; if you approve, it runs.

A plan is a dependency graph

Under the hood a Plan is a DAG — a directed acyclic graph. That’s just a fancy way of saying: tasks point to the tasks they depend on, and there are no loops. A “write the press release” task can wait on a “research the market” task; two independent tasks can run in parallel. The shape decides what’s allowed to start when.

Its lifecycle

pending_approval → running → done

with paused if you stop it mid-flight, and failed or cancelled if a task gives up or you call it off.

A background scheduler does the running:

• It dispatches each task whose dependencies are all satisfied — firing the assigned worker.
• If a task fails, it retries with backoff (waiting a little longer each attempt) up to a budget, then marks the task failed.
• When every task is done, it marks the Plan done and writes a final report — a summary you can read under the plan’s tasks.
• It nudges you with the occasional progress check so a long-running plan never goes dark.

You hold the gate

A Plan never just starts. It begins in pending_approval and waits for your OK — see Budgets & approvals. That’s the safety contract: the app can do a lot of coordinated work unattended, but only after you’ve signed off on the plan it intends to run.

Plans run even when you’re away

Because a Plan is driven by the scheduler rather than by you sitting in a chat, it keeps advancing in the background — and can run on a 24/7 machine in a Fleet. The guardrails (budgets, the kill-switch) still apply.

Let Theodor draft it

You rarely build a Plan by hand. Describe the outcome you want to Theodor and let him propose the breakdown — then tweak and approve.

In practice

Put an approval checkpoint where the cost of being wrong rises, not only at the end. A plan that researches, drafts, and then sends is one where you want the gate before the send — as an explicit task in the graph. Ask for it in the request: “…then stop and get my approval before anything goes out.”

Describe the outcome, not the graph. Theodor wires the dependencies. Your job is to state the finished result and any checkpoints; his job is to decide what runs in what order and who does it. Hand-building a DAG is almost always wasted effort.

Watch for compounding errors on long chains. A task early in the graph that misreads its brief hands wrong material to everything downstream, and the retry logic won’t catch that — retries handle failures, not confidently-wrong output. For a chain longer than about five tasks, put a review step in the middle.

Failure semantics worth knowing: a task retries with growing backoff up to a budget, then is marked failed. Dependent tasks don’t run. The plan can end failed with some work completed — check the board before re-running, or you’ll duplicate the tasks that already succeeded.

When a Plan is the wrong tool

One-off with no dependencies → a plain Task. Same job on a schedule → a Routine. Plans earn their overhead only when steps genuinely depend on each other.

🎓 Learn it hands-on: Plans: multi-step delegation

Terms in this page

• Plan — a coordinated set of tasks with dependencies that the app runs for you after you approve it.
• Task — one concrete unit of work inside the plan; see Tasks.
• Dependency — a “must finish first” link between tasks that controls the order of execution.
• DAG (directed acyclic graph) — the network of tasks-and-dependencies with no loops; it defines what can start when.
• Orchestrator — the worker (usually Theodor) that proposes and coordinates the plan.
• Scheduler — the background process that dispatches ready tasks, retries failures, and finishes the plan.
• Backoff / retry — re-attempting a failed task after a waiting period that grows with each try.
• Final report — the summary written when a plan completes successfully.
• Approval gate — the checkpoint where a plan pauses for your sign-off before it runs; see Budgets & approvals.
• Lifecycle / status — the stages a plan moves through: pending_approval, running, paused, done, failed, or cancelled.