Plan mode

Agent mode with a deliberate review step. Plan mode shows you what the agent intends to do before writing code — the cheapest way to catch a misunderstanding.

Plan mode is the safest way to make non-trivial changes in vly. Before any code is written, the agent shows you a written plan — the schema changes, pages affected, components to add — and waits for your approval. You can edit the plan directly or reply with refinements before approving.

The cost is 5–15 extra seconds per change. The savings, when the agent misreads your intent, are minutes-to-hours.

When to use it

✅ The first prompt of any project

Sets the foundation. Catching a wrong schema decision now saves you a rewrite later.

✅ Schema changes

Migrations are the most expensive thing to undo. See the migration plan first.

✅ Big features

“Add billing” or “Add multi-tenant workspaces” — both touch many files. Worth a plan review.

✅ When you're unsure

If you can’t tell whether your prompt will produce what you want, Plan mode resolves the ambiguity for cheap.

❌ Tiny tweaks

“Make this button violet” — just use Agent mode or Code mode.

❌ When you've already iterated three times

By now, the project structure is stable; agent decisions are predictable. Switch to Agent mode for momentum.

Anatomy of a plan

A typical plan has four sections:

1. Summary

   One paragraph restating what you asked for, in vly’s own words. Read this first — if vly’s restatement misses the point, fix the prompt before the plan.

2. Schema changes

   Concrete table-by-table changes — new tables, new fields, new indexes, migrations needed. Includes a pre/post diff.

3. Pages and components

   What’s added, edited, or removed. Includes the React Router changes and the affected components.

4. Integrations and side-effects

   Any third-party services to wire up (Stripe, Resend, OpenAI, etc.) and any environment variables you’ll need to provide.

A worked example

You write:

vly returns a plan that looks roughly like:

## Summary
Add team-level Stripe subscriptions with three plan tiers, an admin-only
billing UI, and a banner for past-due subscriptions.

## Schema changes
- Add `subscriptions` table:
    - teamId: id<"teams">
    - stripeCustomerId: string
    - stripeSubscriptionId: string
    - planTier: "free" | "pro" | "business"
    - status: "active" | "past_due" | "cancelled"
    - currentPeriodEnd: number
    - Index: by_team [teamId]
- Add `stripeCustomerId` field to `teams` table

## Pages and components
- New: /settings/billing (admin only)
- New: <BillingBanner /> in the app shell, shown when status === "past_due"
- New: <PlanCard /> component, three of them on the billing page
- Edited: middleware to redirect non-admins from /settings/billing
- Edited: /settings layout to add a "Billing" tab

## Integrations and side-effects
- Stripe integration (will prompt for STRIPE_SECRET_KEY,
  STRIPE_WEBHOOK_SECRET, and three STRIPE_PRICE_ID_* values)
- New Convex action: handleStripeWebhook
- Webhook endpoint: /api/stripe-webhook (you'll register this URL in
  the Stripe dashboard)

You read it. Maybe you notice “Business should be $39, not$40.” You reply:

vly updates the plan, you approve, and the agent writes ~15 files in 90 seconds, including a webhook handler that handles the deferred downgrade correctly.

The alternative would have been: agent writes the wrong price + no deferred downgrade, you discover it on the second test, you re-prompt twice. Plan mode saved two roundtrips.

Editing the plan directly

You don’t have to reply in prose. Click any line in the plan to edit it inline:

Common direct edits:

Rename a table

Click the table name. Rename. Plan re-validates references.

Drop a field

Click the field. Delete. Plan removes it from the schema and any pages that referenced it.

Change a type

Click the type. Edit. Plan re-runs the migration step against the new type.

Add a new entity

Click ”+ table” at the bottom of Schema changes. Define inline.

Approving and skipping

Three buttons appear at the bottom of every plan:

• Approve and build — write the code as planned.
• Refine — return to the prompt with the plan as context, write a follow-up.
• Cancel — discard the plan; no changes are made, no credits charged.

Plans don’t cost credits to generate. Only the build does. So always plan, never feel rushed to approve.

Tips

Read the Summary out loud. If it doesn’t match what’s in your head, your prompt was the problem — fix the prompt, not the plan.

Use Plan mode for unfamiliar integrations. When adding Stripe, Twilio, or anything you haven’t wired up before, the plan reveals which env vars and webhook URLs you’ll need before you commit.

Plans are part of version history. Every plan you approve is saved alongside the resulting revision. You can read the original plan months later in version history.

When Plan mode isn’t enough

Some changes are big enough that even a plan review feels under-baked. For those:

Branch first

Make the change on a branch, test it end-to-end, merge or discard. Plan + branch = the safest possible workflow.

Talk first, build later

Use Agent mode to ask vly to describe an approach in chat, without acting. Then once you agree, ask it to do the thing.

Related

Agent mode

The default. No plan review, faster iteration.

Code mode

Hand-edit when a prompt is overkill.

Iterating effectively

Patterns for momentum across long sessions.