---
title: Plan then execute
description: Have the main model write a plan with a check per step, approve or edit it, then let cheap workers carry out each step while the main model verifies it with /plan-exec.
section: automation
order: 20
audience: [user, agent]
sources: [docs/plan-execute.md, packages/harness/src/extensions/plan-exec.ts, packages/harness/src/planexec/plan.ts, packages/harness/src/planexec/run.ts, docs/venom-config.schema.json]
features: [automation.plan-exec]
---

For a big task: the main model investigates and writes a plan, you approve or edit it, workers on the fast tier carry out the steps, and the main model checks each step before the next one starts.

## Example {#example}

```text
/plan-exec add retries with backoff to the uploader     plan it, then run it
/plan-exec on                                           plan every task prompt in this session
/plan-exec resume                                       continue a run that stopped or was interrupted
```

To make it the default for a gear, set `mode: plan-execute` on that gear in `venom.yaml`. Engaging a gear without it turns it off again.

```yaml
gears:
  power:
    mode: plan-execute
plan_execute:
  approve: ask
```

## Commands {#commands}

| Command | What it does |
|---|---|
| `/plan-exec <goal>` | Plan first (read-only), approve or edit, then run each step. |
| `/plan-exec on` / `off` | Plan every plain prompt in this session. |
| `/plan-exec resume [id]` | Continue an interrupted run at its first unfinished step. A failed step gets one more try. |
| `/plan-exec run <file>` | Run a plan file you wrote (`.venom/plans/*.md` with a `plan-steps` block). |
| `/plan-exec status` | The checklist and the cost so far. |
| `/plan-exec stop` | Stop after the step in flight. |

Short questions (under 120 characters, ending in `?`) and slash commands are never planned.

## What happens {#steps}

1. **Plan.** The session enters plan mode (read-only). The main model writes `.venom/plans/<time>-exec.md`: a short rationale and one fenced `plan-steps` block. At most 40 steps. A plan that does not parse goes back to the model with the error, twice at most.

   ````markdown
   ```plan-steps
   [{ "title": "Add the retry helper",
      "do": "everything a worker needs: files, the change, constraints (it cannot see this conversation)",
      "check": { "command": "npm test -- retry", "expect": "the helper retries 3 times with backoff" } }]
   ```
   ````

   Every step has a `check`: a command that exits 0 when the step is done, a sentence saying what must be true, or both.
2. **Approve.** The TUI shows the steps and their checks and asks Run it / Edit the plan / Cancel. Edit opens the plan as JSON in your editor and checks it again. With `plan_execute.approve: auto` the question is skipped. A session with no UI (headless, scheduled) always runs the plan as written.
3. **Execute.** Plan mode ends (back to your previous mode, or `accept-edits`). Each step runs on a `worker` subagent on the fast tier with a fresh context: the goal, the plan's titles, what earlier steps reported, its own step and check.
4. **Verify.** The `verifier` agent on the main model runs the check command under your permission rules (or the narrowest check that shows the acceptance sentence) and answers `PASS` or `FAIL`. Nothing is taken on the worker's word.
5. **Retry once.** A failed check re-runs the step with the verifier's findings, on the escalation tier when auto-escalation is on (`escalation`, default `{ max: 1, to: smart }`), else the same tier. A second failure stops the run at that step.
6. **Replan, at most twice.** When a step fails its retry, the main model gets one replanning round and must propose at least one new step. Steps that repeat a done or failed step (same normalized title and check) are dropped; if none is left the run ends `stalled`. Replans count toward the run's cost and are checkpointed, so a crash loop cannot exceed the bound.

While it runs, the TUI shows a checklist with each step's cost (worker and verifier together):

```text
plan-execute: add retries with backoff to the uploader [running]
● 1. Add the retry helper  $0.012
◐ 2. Use it in the uploader  working (retry 1) · $0.021
○ 3. Document the setting
1/3 steps · total $0.033
```

When the run ends, the main model gets one message with each step's outcome so its next turn builds on it.

## Checkpoints and resume {#resume}

The run's step state is saved at every step boundary. After a crash, a reboot, a closed terminal or a usage limit, `venom resume` (or `/plan-exec resume`) continues at the first step that is not done. A step that was in flight is redone; its worker's edits are already in the working tree and the verifier judges the result. A usage limit with a reset time during a step waits for the reset (or switches to `resume.fallback_gear`) and repeats the call without counting a failed attempt. See [Long tasks and resume](/docs/automation/long-tasks.md).

## Settings {#settings}

| Key | Type | Default | What it does |
|---|---|---|---|
| `plan_execute.approve` | `ask` \| `auto` | `ask` | `auto` runs the plan without asking. |
| `gears.<name>.mode` | `plan-execute` | off | Plan every task prompt while that gear is engaged. |
| `escalation` | object \| `false` | `{ max: 1, to: smart }` | The tier a failed step's retry runs on; `false` keeps the same tier. |

## Limits {#limits}

- Steps run one after another. For parallel work inside a step the worker can use the `task` tool; for a pipeline of your own shape, write a [workflow](/docs/automation/workflows.md).
- The planning request is a user message and workers are child sessions, so the system prompt and tool list never change and the prompt cache stays warm.
- The verifier is the main model's judgment backed by a command. A check with a command is stronger than one with only a sentence.

## Related

- [Spec to pull requests](/docs/automation/spec-to-pr.md) runs one plan-execute run per slice.
- [Long tasks and resume](/docs/automation/long-tasks.md).
