Agent mode

The default mode for vly. Describe a change; the agent decides what to edit, plans implicitly, and writes code. Best for most everyday work.

Agent mode is the default workflow in vly. You describe what you want — anything from “make the buttons bigger” to “add Stripe subscription billing” — and the agent decides what files to touch, what schema to change, and what code to write. Plan and code happen as a single, fast cycle.

When to use it

✅ Most everyday edits

Adding a feature, fixing a bug, restyling, refactoring. If you’re not sure which mode to use, start here.

✅ Multi-file changes

Edits that touch the schema and a page and a component. The agent traces dependencies for you.

✅ When you trust the prompt

Your prompt is clear and the change feels low-risk. Skip the Plan-mode review step.

❌ Schema migrations on production

Use Plan mode so you can review the migration before it runs.

How it works

A few things worth noting:

• The agent reads your full project context before generating, not just snippets. It knows the schema, the auth model, your custom instructions, your design system.
• Type-check failures auto-retry up to three times. You only see the build that succeeded.
• Conflict-free for files you’ve manually edited. If you edited components/Header.tsx by hand and the agent decides to change it, the agent will respect your edits as the new starting point.

Anatomy of a good agent-mode prompt

Three things make a prompt land cleanly:

1. Be concrete about the user-facing behavior

   “Add a settings page where users can change their display name and avatar” beats “Add a settings page”.

2. Mention scope

   “Just for the logged-in user — admins shouldn’t see anyone else’s settings here.”

3. Reference existing things by name

   “Add a column to the existing Tasks table called notes (optional text)” beats “add a notes feature to tasks”.

A worked example:

The bad version forces the agent to guess at six decisions. The good version is unambiguous.

Switching agents per prompt

Agent mode runs against your default agent (set in workspace settings), but you can override per-prompt:

Claude Code

The default. Strong reasoning across many files. Best general-purpose pick.

OpenAI Codex

Fast, surgical. Best on small, targeted changes (one file, one function).

Gemini CLI

Best for multi-file design work and schema modeling.

See Choosing an agent for the full decision tree.

What you can ask for

Add a feature

Add a "Favorites" feature to the task list. Each user can favorite tasks
by clicking a star icon on each row. Favorited tasks appear in a separate
"My Favorites" section at the top of the page, sorted by most recently
favorited.

Refactor

Refactor the task list to use a shared `<TaskRow />` component instead of
duplicating the markup. The component should accept the task object and
render the title, due date, priority, and assignee avatar.

Schema change

Add an `archived` boolean field to the `tasks` table (default false). When
true, the task doesn't show in the default list. Add an "Archive" action
in the task menu that toggles this. Add a separate "Archived" view that
lists only archived tasks, with an "Unarchive" action.

Integration

When a task is marked done, post a message to our team's Slack channel
`#shipped` with the task title and who completed it. Use the Slack
integration.

Performance fix

The dashboard is slow when there are 100+ tasks. Add pagination — show
25 per page with prev/next buttons. Use a Convex paginated query.

When the agent gets it wrong

The agent is good but not infallible. Common failure modes:

It misinterpreted the prompt

Switch to Plan mode so you see the plan before code is written. Often the misread is visible in the plan and you can correct it in one reply.

It made the change but broke something else

Roll back via version history (one click). Then re-prompt with the additional constraint: “Same change, but don’t break the existing <Header /> layout.”

It picked an integration you didn't want

Be explicit. “Use Resend for email (not SendGrid)” or “Use the existing Convex storage for files (not S3).”

It generated working code but it doesn't match your style

Add a custom instruction so this preference is global. Then re-prompt with “Refactor according to my custom instructions.” Easier than fighting it every time.

Tips

Iterate in small chunks. Five small prompts beat one giant one. Easier to roll back, easier to reason about, easier for the agent to get right.

Reference your custom instructions explicitly when needed. “As per my custom instructions, do X” is a valid prompt and surfaces relevant rules.

Use Plan mode for the first prompt of any project. Once you trust the project’s shape, drop back to Agent mode for incremental work.

Related

Plan mode

Same flow, with a review step before code is written.

Code mode

Hand-edit when a prompt is overkill.

Iterating effectively

Patterns for making 50 small changes a day.