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.

• 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. Nothing is edited yet.
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. If a step turns out to be wrong, stop the run and edit the plan before continuing.

Revising a plan mid-flight

Plans are files, so revising one is an edit.

1. Open the plan file in your editor.
2. Change the steps, files, risks, or verification section.
3. Ask the agent to follow the updated plan — for example, "continue, but follow the plan file as it is now".

The agent re-reads the plan from disk, so your edit becomes the source of truth for the rest of the run.

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.