Plan then execute
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.
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
/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 interruptedTo 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.
gears:
power:
mode: plan-execute
plan_execute:
approve: askCommands
| 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
Plan. The session enters plan mode (read-only). The main model writes
.venom/plans/<time>-exec.md: a short rationale and one fencedplan-stepsblock. At most 40 steps. A plan that does not parse goes back to the model with the error, twice at most.```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.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: autothe question is skipped. A session with no UI (headless, scheduled) always runs the plan as written.Execute. Plan mode ends (back to your previous mode, or
accept-edits). Each step runs on aworkersubagent on the fast tier with a fresh context: the goal, the plan's titles, what earlier steps reported, its own step and check.Verify. The
verifieragent on the main model runs the check command under your permission rules (or the narrowest check that shows the acceptance sentence) and answersPASSorFAIL. Nothing is taken on the worker's word.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.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):
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.033When the run ends, the main model gets one message with each step's outcome so its next turn builds on it.
Checkpoints and 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.
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
- Steps run one after another. For parallel work inside a step the worker can use the
tasktool; for a pipeline of your own shape, write a workflow. - 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 runs one plan-execute run per slice.
- Long tasks and resume.