Plan files

Vortex runs the same loop every time: understand, plan, implement, verify. The plan step produces a file you can read and edit before any code changes. That file is the checkpoint between "the agent understands the job" and "the agent starts editing".

What a plan file is

Plan mode writes an editable plan to <workspace>/.vortex/plans/<name>.plan.md. You read it, edit it if needed, and only then let the agent implement it.

While the plan is still being written, a tab opens and shows the markdown as it streams. The view follows the bottom until you scroll up. The footer shows how long it has been writing and how much text has arrived. Before the first field, the tab says it is waiting. When the file lands, that tab becomes the plan file.

The agent asks what the plan covers at the start, after a short look at a few files. The choices are about the plan. Building waits until you press Build. Search and read stay available for the whole plan. A broad look across several areas goes to parallel scout or explore children, and a specific file is read directly. An edit or review child stays blocked until Build.

• It is plain Markdown, so it diffs and reviews like code.
• It lives in the workspace, not in a private store, so you can commit it or ignore it.
• It is written to disk even when Review mode is on, because plan files are plan-mode safe and carve out of patch staging.

Review mode stages agent edits as pending patches. A plan file is the artifact you look at before those patches exist.

How a plan fits the loop

1. Understand. Ask mode, or an Agent run, reads the workspace with on-device retrieval: lexical, symbol, path, outline, and reference search. There is no repo upload.
2. Plan. Plan mode writes the plan file. Registered MCP tools are callable here, so the plan can look something up before any edit. Adding or configuring a server still waits until Build.
3. Review the plan. Read the file. Add constraints, remove steps, fix the approach.
4. Implement. The agent follows the plan, editing across files and running terminal commands.
5. Verify. A verification check can require a specific exit code and an output phrase.

Plan mode can also create a reviewed plan for a change you describe in chat, so you do not have to phrase the job as a prompt template.

A worked example

## Add a --dry-run flag to the deploy command

## Goal

The example CLI's `deploy` command gains a `--dry-run` flag that prints the
resolved deploy plan and exits without touching the target.

## Steps

1. Parse `--dry-run` in `src/cli/deploy.rs` alongside the existing flags.
2. Short-circuit after the deploy plan is resolved and before the first write.
3. Print the plan in the same format the real run logs.
4. Add a test that asserts no write happens when `--dry-run` is set.

## Files

- `src/cli/deploy.rs`
- `src/cli/deploy/tests.rs`
- `docs/deploy.md`

## Risks

- The flag must not change behaviour when it is absent.
- The plan printer must not leak credentials from the environment.

## Verification

- `cargo test deploy -- --nocapture`
- Manual: `deploy --dry-run` on a scratch workspace exits 0 and writes nothing.

The shape is not mandatory, but goal, steps, files, risks, and verification are the five sections that pay for themselves. The verification section is where you write down what "done" means, and it is what the agent turns into a check.

From plan to work items

A multi-step plan becomes a list of todo items that the agent works through. Each step reports as it completes, so you can follow progress in the transcript and see which step is active. During a sequential build, the next ready task is marked in progress as the run moves, including the checkbox in the plan file, so the card does not sit at 0 of N until a final update. A task that still depends on unfinished work stays pending. In an SSH workspace that checklist is read from the host, where the plan file lives. While that build is running, the checklist stays in place until you scroll past it, then holds at the top of the transcript. When the run finishes, the card returns to the turn as its result. A plan that leaked in from another chat is dropped from this card on open; the file stays on disk and still appears under Other plans. A follow-up in the same chat keeps that checklist: a status update cannot drop rows the model did not mention. The run does not finish while items are still open. When every task is completed, the card says so and the check turns green; the card itself stays the same surface as the rest of the transcript. If a step turns out to be wrong, stop the run and edit the plan before continuing.

Each task is written so it stands alone: what changes, the files, and how to tell it is done. A parallel build hands one task to a sub-agent and names the plan file, so that sub-agent can read the section when the task line is not enough. When that sub-agent needs an approval or an answer, the request shows in this chat and on the worker, including if it arrives before the worker has announced itself.

Revising a plan mid-flight

Plans are files, so revising one is an edit — and there are two ways to make it.

Ask the agent to revise it. Reply to the plan in Plan mode with what should change ("also handle X", "split step 3", "that approach is wrong"). The agent reads the plan file and rewrites that file in place, so the Build button, the editor tab, and the plan list all keep pointing at one artifact. The rewrite includes the checklist. A plan with no tasks is refused, so a revision cannot save a file that has nothing to track. A follow-up that is a genuinely separate job writes a new plan file instead; the two cases are distinguished by whether the agent passes the existing path to create_plan.

Edit it yourself. Open the plan file in your editor, change the steps, files, risks, or verification section, and save. Then:

1. Ask the agent to follow the updated plan — for example, "continue, but follow the plan file as it is now".
2. If the agent has the plan open as the active file, it re-reads it from disk, so your edit becomes the source of truth for the rest of the run.

If you edit the plan but do not save it, the agent still rewrites the file on disk — the editor keeps your unsaved text and shows the usual "changed on disk" bar rather than clobbering it. Save first if your edit should win. Checklist ticks are not written back to an unsaved buffer either.

Every plan in the workspace

The planning card leads with the plan this run produced. Other plans in this workspace is a separate disclosure: it lists the rest of .vortex/plans/, and Vortex does not read those files until you open it. Each row shows how far that file's checklist has got, and the action that applies to that file:

• Build when nothing has started yet.
• Continue when some tasks are already done or in progress.
• Parallel when at least two tasks remain.
• A row with no button has nothing left to execute.

The session's own row follows the live checklist, which can be ahead of the file on disk. Rows under Other plans follow each file.

Delete is on that nested list. It removes the plan file. Revision snapshots in .vortex/plans/history/ stay until their own plan is deleted; they are the only undo a revision has, because .vortex/ is gitignored.

In an SSH workspace the list is the host's: listing and delete run on the machine that owns the files, so an empty list means there are no plans, not that the Mac could not see them.

Plan files in version control

<repo>/.vortex/ is repo-owned and safe to delete. You can:

• commit it if you want plan history next to the code, so a reviewer can see what was agreed before the diff;
• ignore it if plans are scratch notes, by adding .vortex/ to .gitignore.

Either way, plan files never land as pending patches, because they are plan-mode safe.

When to skip planning

Skip the plan step for one-line fixes: a typo, a version bump, a renamed variable, an extra log line. Plan mode costs a round trip, and for a change you can describe in one sentence, the plan is the sentence.

Plan first when the change crosses files, touches a public interface, needs a migration, or when you are unsure which approach is right. If you cannot say what "done" means yet, you are not ready to implement.

Next steps

• Review mode — approve or reject each patch after implementation.
• Quickstart — the full loop from invite to finished change.
• Models and keys — choose which model plans and which one implements.

Get an invite

Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite and a download link.