Authoring plans

A visual plan is a single page that lays out a piece of work as structure instead of paragraphs: a numbered sequence of steps, a diagram of how the pieces fit, the files that change, the tradeoffs that were weighed. An AI agent writes the plan; you read it at a glance, instead of wading through a wall of terminal text.

This page is a tour of the pieces a plan is built from, and what each one looks like once rendered. You do not write these by hand: an agent assembles them, taught by the visual-plan skill, which carries the exact syntax. Here the focus is on what a plan is made of and why each piece earns its place.

How a plan is shaped

Every plan opens with a title and an optional sentence or two of context, then is composed, top to bottom, from a small, fixed set of building blocks. The same handful of pieces covers a code change, a database migration, or a product launch; the agent reaches for the ones that fit the work and skips the rest. The blocks below are roughly in the order you would meet them in a plan.

Phases: the backbone

Most plans are a sequence of steps, and a phase is how that sequence is drawn: a numbered vertical timeline. Each step carries a status, so at a glance you can see what is done, what is in progress, and what is still ahead.

Diagrams: the shape of the work

When a plan has structure, a request path, a set of services, a state machine, a diagram says it faster than a paragraph. Plans draw these as diagrams that pick up the page’s light or dark theme automatically.

Callouts: what to pay attention to

Risks, decisions, and notes do not belong buried in prose. A callout lifts them out, color-coded by kind, so the one thing you must not miss is the one thing that stands out.

File changes: what gets touched

For a code change, the fastest way to convey scope is a map of the files involved, added, modified, deleted, or moved. The file tree draws that map so the blast radius is obvious before you read a single line.

Charts: the numbers

When a plan involves quantities, effort, latency, traffic, rows, a small chart shows the shape of the data better than a list of figures. Plans render real bar, line, and pie charts.

Comparing options

When there is a real choice to make, a comparison lays the options side by side as pros and cons, with the recommended one marked, so the reasoning is visible rather than asserted.

For scoring several options against several criteria at once, a matrix is a compact scorecard with the recommended column highlighted.

Questions and checklists

Open questions that need a decision before work starts get their own list, so they are not lost in the prose and the reader knows exactly what is being asked of them.

A plan usually closes with a checklist: the definition of done, the conditions that mean the work is actually finished.

Code and math

Where a specific snippet or a formula carries the point, a plan can embed syntax-highlighted code and typeset math, both rendered inline rather than described.

export async function allow(key: string): Promise<boolean> {
  const count = await redis.incr(key)
  if (count === 1) await redis.expire(key, WINDOW_SECONDS)
  return count <= MAX_REQUESTS
}

Seeing it all together

Those pieces are the whole vocabulary. To see them combined into real plans, open one from the Examples in the sidebar. To render a plan of your own from an .mdx file, see the CLI reference.