Skip to content

Plan a multi-agent change

This guide turns a change that is too large for one agent into a reviewed plan with ordered phases. It assumes the goal is clear but the decomposition is not; if the work fits one agent, run it directly instead.

Before you start

You need a checkout where sase runs and a project with plan storage configured. No running agent is required.

1. Write the plan file and validate it

Write a Markdown plan with frontmatter naming its tier: tale for work one agent implements directly, epic for work split into phases with id, title, depends_on, and size entries. Keep the body to the outcome, the phases, and the decisions the reviewer must make.

Check the schema before proposing anything:

sase plan validate sase_plan_feature.md

The validator reports every problem in one pass with the field at fault. Fix those lines and re-run until it passes.

2. Propose the plan and get it approved

Submit the file for review:

sase plan propose sase_plan_feature.md

Approve it from the TUI or the CLI. An epic needs its kind stated explicitly so it is never launched as a single agent by accident:

sase plan approve sase_plan_feature --kind epic

Approval archives the plan and starts the work: a tale launches its coder, while an epic hands its phases to the bead tracker. Answer any plan decision at approval time with a repeated -D id=value flag.

3. Follow the phases through

Preview what an epic will launch before it starts, then launch it:

sase bead work sase_plan_feature.md --dry-run
sase bead work sase_plan_feature.md --yes

Track progress with the bead list and the plan list. Each phase runs its own agent, so a stuck phase can be retried without redoing the phases that already landed.

If it goes wrong

A plan that never leaves review usually failed validation or is waiting on a decision: re-run the validator and check the pending approvals with sase plan. For a phase that fails or never starts, see Unstick a queued agent.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.