---
audience: everyone
summary: "Stateful multi-step plans an AI commits to, works through, and recovers\
  \ from \u2014 with you as the supervisor."
title: Planner
path: concepts/planner
status: published
---

# Planner

The planner is how an AI handles work that needs more than a single
turn but less than full delegation. Instead of stalling the
conversation or fanning out a bunch of sidekicks, the AI writes a
plan, commits to it, and works through it step by step.

You're the supervisor: pause, resume, cancel at any point.

## Anatomy of a plan

A plan has:

- A **goal** — one-sentence summary of what's being accomplished.
- A **state**: `draft`, `running`, `paused`, `done`, `failed`,
  `cancelled`.
- A **mode**: `sequential` (work steps one at a time, each builds on
  the previous) or `parallel` (fan out as sidekicks; merge results).
- An **advance** setting: `auto` (continue without your nudge,
  bounded by a budget) or `manual` (each step waits for you).
- A **venue**: `main` (runs in the current room) or `sidekick` (spawns
  a sidekick room and runs there; main chat stays clean).
- A list of **steps**, each with a 5-character `id`, text, status
  (`pending`, `in_progress`, `done`, `failed`, `skipped`), a `result`
  the AI fills in on completion, and an `attempts` counter.

## The plan card

When a plan is active, a **plan card** mounts above the chat timeline
showing:

- State badge + goal.
- Each step with a glyph: ○ pending, ▶ in progress, ✓ done, ✗ failed,
  — skipped.
- The current step pointer (an underline marker).
- An auto-budget indicator (`⚡N`) when `advance=auto` — how many more
  steps the AI can do before pausing for your check-in.
- **Pause / Resume / Cancel** buttons. Always visible.

Per-step results expand on click; you can see exactly what the AI
recorded for "step 3 done".

## The lifecycle

```mermaid
stateDiagram-v2
    [*] --> draft: write
    draft --> running: run
    running --> paused: pause • retry cap hit • step_failed(revise)
    paused --> running: resume
    running --> done: all steps terminal, none failed
    running --> failed: step_failed(abort)<br/>or any step failed
    draft --> cancelled: cancel
    running --> cancelled: cancel
    paused --> cancelled: cancel
    done --> [*]
    failed --> [*]
    cancelled --> [*]
```

- **draft** — written but not started. Can be edited freely.
- **running** — the AI is working.
- **paused** — the AI is waiting. Reasons: supervisor pause, retry
  cap hit on a step, `next='revise'` on a `step_failed` call.
- **done** — all steps reached a terminal status; none failed.
- **failed** — all steps terminal; at least one failed.
- **cancelled** — supervisor stopped it.

## Failure recovery

If a tool call inside a step errors, the harness adds a nudge to the
error result:

> Plan harness: this is step 3/5, attempt 1/3. If the error suggests
> fallbacks above, try the one that best fits the user's intent.
> Reserve `step_failed` for when you've genuinely run out of angles.

Combined with plugin-side fallback hints (e.g. ScaiDrive errors
suggest `web_search`), this prevents the "give up at the first 401"
failure mode.

Each step gets up to **3 attempts** before being forced-paused for
your decision. The AI can also voluntarily call `step_failed` with
one of four `next` actions:

| `next` | What it means |
|---|---|
| `retry` | I have a different angle. Try again. |
| `skip` | This step can't be done; advance to the next. |
| `abort` | Plan is broken; terminate. |
| `revise` | Pause; the plan itself needs rewriting. |

## The auto-step throttle

When `advance=auto`, the AI continues through steps without your
intervention. To prevent runaway behaviour:

- Counter `consecutive_auto_steps` increments after each automatic
  advance.
- When it hits `max_consecutive_auto_steps` (default **8**), the
  harness forces a pause. You see the plan card in `paused` state.
- Any message you send resets the counter to 0.

## Caps and invariants

- **At most one active plan per room**. The AI can't start a second
  plan while one is running, paused, or in draft.
- **Max 20 steps per plan**. If the work genuinely needs more, the
  AI splits it.
- **Plans don't survive room close**. Cancelled when the room is
  closed. Archived rooms keep their plan history for audit.

## When to use which

- **Single tool call answers a question** → no plan. Just ask.
- **Background research with independent subtasks** → `parallel`
  mode (or a [sidekick](/docs/scaiwave/concepts/sidekicks)).
- **Multi-step task with dependencies** → `sequential`, default mode.
- **Long-running task you don't want cluttering the chat** →
  `venue=sidekick`.

## Where to go next

- Tutorial: [Use the planner](/docs/scaiwave/tutorials/power-user/use-the-planner).
- [Sidekicks](/docs/scaiwave/concepts/sidekicks) — for purely
  delegated work.
- API: [Plans](/docs/scaiwave/reference/api/sidekicks-and-plans).