> For the complete documentation index, see [llms.txt](https://docs.riff.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.riff.ai/archive/features-legacy-databutton-web-app-builder/agent-planning-mode.md).

# Agent Planning Mode

Planning Mode changes the agent’s operating instructions so it focuses on research, validation, and strategy instead of immediately making edits. It’s designed to prevent accidental or premature changes while you’re still figuring things out.

It can be used in one of two ways:

* Use the Planning Mode toggle in the chat interface.
* When the agent requests a mode switch, you’ll see a confirmation modal.

{% columns %}
{% column %}

{% endcolumn %}

{% column valign="middle" %}

{% endcolumn %}
{% endcolumns %}

### Default Mode vs. Planning Mode

#### Default Mode (Normal)

This is the standard state.

Agent behaviour:

* Optimized for implementation and shipping
* Proactively writes code, creates files, runs tests, and wires features together

When to use:

* Requirements are clear and you want the agent to execute

#### Planning Mode

A focused state for research and architecture.

Agent behaviour:

* Prioritizes investigation, clarification, and proof before changes
* Will propose a plan and checkpoints before switching back to build

What it can still do:

* Read and search your codebase
* Inspect configuration and app structure
* Run “safe” experiments (for example: quick scripts to validate assumptions)
* Summarize findings and recommend next steps

{% hint style="info" %}
Planning Mode is an *instructional guardrail*, not a hard security boundary. It nudges the agent to avoid permanent changes until you intentionally switch back to Default Mode.
{% endhint %}

### How switching modes works

1. The agent requests a mode switch
   * Target mode: planning or default
   * Message: a short explanation of why it wants to switch
2. Riff asks you to confirm
   * The mode does not change until you approve
3. You confirm (or cancel)
   * Confirm: Riff switches modes and updates the agent’s operating instructions
   * Cancel: nothing changes; the agent stays in the current mode

### Key features

* Clear “think vs. build” workflow: helps avoid rushing into implementation
* Explicit confirmation step: mode only changes when you approve
* Great for complex work: encourages research, verification, and structured plans before edits

### How to use

1. Start in Default Mode and describe what you want to do.
2. If you’re still exploring, switch to Planning Mode.
3. Ask the agent to:
   * Investigate the codebase
   * Validate assumptions (APIs, data, edge cases)
   * Propose a step-by-step plan with a definition of done
4. When you’re ready to implement, switch back to Default Mode.

### Example

Scenario: “Let’s think first”

User: “I want to switch our payment provider to Stripe, but I’m worried about breaking existing subscriptions.”

In Planning Mode, the agent will likely:

* Find all references to the current provider
* Identify subscription flows and risks
* Draft a migration plan and test strategy
* Recommend validation checks

Then you switch back to Default Mode to implement the changes.

### Tips

* Pair Planning Mode with Tasks for a clean “plan → build” loop.
* If the agent starts implementing too early, toggle Planning Mode and ask for:
  * an explicit plan
  * acceptance criteria
  * a short risk checklist


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.riff.ai/archive/features-legacy-databutton-web-app-builder/agent-planning-mode.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.