Understanding Modes¶

Modes are runtime behavior overlays that modify how an agent operates without changing the underlying bundle. When a mode is active, the agent receives mode-specific guidance and tool policies are enforced -- giving you fine-grained control over what an agent can and cannot do in a given context.

What You'll Learn¶

• What modes are and why they exist
• How to activate, list, and deactivate modes from the command line
• How tool policies control agent capabilities at runtime
• How agents interact with modes programmatically
• How to create custom modes for your projects and workflows

What is a Mode?¶

A mode is a runtime behavior constraint defined as a markdown file with YAML frontmatter. When activated, it does two things:

1. Injects guidance into the agent's context as a system reminder
2. Enforces tool policies that control which tools the agent can use

Think of modes as guardrails you can snap on and off during a conversation. A "plan" mode might let the agent read and search code but block it from writing files. A "debug" mode might encourage deep investigation before any fixes. The agent's underlying bundle stays the same -- only its runtime behavior changes.

Key Characteristics¶

• Toggleable: Activate and deactivate modes at any point in a conversation
• Non-destructive: Modes overlay behavior without modifying bundles or configuration
• Enforceable: Tool policies are enforced at the system level, not just suggested
• Composable with bundles: Any bundle can work with any mode
• User and project scoped: Define modes globally or per-project

Activating Modes¶

From the Command Line¶

Users control modes through slash commands during a conversation:

When a mode is active, your prompt changes to include a visual indicator:

[plan]> What modules handle authentication?

This makes it immediately clear which behavioral constraints are in effect.

Quick Example¶

> /mode plan
Mode activated: plan - Planning mode, analysis only

[plan]> Analyze the authentication flow and suggest improvements

  (agent reads files, traces code, produces analysis...)

[plan]> Now implement the changes

  Tool blocked: write_file is not available in plan mode.
  Deactivate plan mode with /mode off to enable implementation.

> /mode off
Mode deactivated: plan

> Implement the authentication changes we discussed
  (agent proceeds with full tool access...)

How Modes Work¶

When you activate a mode, three things happen behind the scenes:

1. Context Injection¶

The mode's markdown content is injected into the agent's context as a system reminder:

<system-reminder source="mode-plan">
# Planning Mode

You are in planning mode. Focus on analysis and design, not implementation.
Explore the codebase, understand the architecture, and produce a clear plan
before any code changes are made.
</system-reminder>

This guidance shapes the agent's behavior through its instructions, just like any other context. The agent "knows" it is in a particular mode and adjusts its approach accordingly.

2. Tool Policy Enforcement¶

Each tool is assigned a policy that controls how it behaves while the mode is active. These policies are enforced at the system level -- the agent cannot bypass them.

3. Prompt Indicator¶

The user's prompt updates to show [mode-name]>, providing a persistent visual reminder that constraints are in effect.

Tool Policies¶

Tool policies are the enforcement mechanism that gives modes their teeth. Each tool in a mode configuration is assigned one of four policies:

The Default Action¶

Every mode defines a default_action that applies to any tool not explicitly listed in the configuration. This is typically set to block, meaning tools must be explicitly allowed:

mode:
  tools:
    safe:
      - read_file
      - grep
      - glob
    # Everything else is blocked
  default_action: block

Tip: A default_action: block with explicit safe entries follows the principle of least privilege -- only the tools you specifically allow are available.

Policy Examples¶

Safe -- the agent uses the tool without any interruption:

[plan]> Let me check the project structure.
  (agent calls glob -- works normally)

Warn -- first attempt is blocked, but the agent can retry:

[plan]> Let me run the tests to verify.
  Warning: bash is restricted in plan mode. Call again to proceed.
[plan]> Running tests is necessary to validate the analysis.
  (agent retries bash -- proceeds on second attempt)

Confirm -- requires you to approve each use:

[debug]> I need to apply a temporary fix.
  edit_file requires approval in debug mode.
  Allow this edit? [y/n]

Block -- the tool is unavailable entirely:

[plan]> I'll create the implementation file now.
  Tool blocked: write_file is not available in plan mode.

The mode Tool (Agent-Initiated)¶

Modes are not just a user-facing feature. Agents can also query and change modes programmatically using the mode tool:

# List all available modes
mode(operation="list")

# Check which mode is currently active
mode(operation="current")

# Request activation of a specific mode
mode(operation="set", name="plan")

# Deactivate the current mode
mode(operation="clear")

Gate Policy¶

By default, agent-initiated mode changes use a warn gate policy. This means:

1. The agent's first request to change modes is blocked with a notice
2. If the agent calls again, the mode change proceeds

This prevents accidental mode switches while still allowing agents to manage modes when they have a clear reason to do so.

Tip: The gate policy protects against an agent inadvertently dropping into an unrestricted mode to bypass constraints. The double-call requirement ensures intentionality.

When Agents Change Modes¶

Agents typically change modes as part of structured workflows. For example, a recipe might instruct an agent to:

1. Enter plan mode to analyze a problem
2. Switch to execute-plan mode to implement the solution
3. Activate verify mode to confirm completion

This pattern enables multi-phase workflows where each phase has appropriate tool constraints.

Creating Custom Modes¶

You can define custom modes tailored to your team's workflows by creating markdown files with YAML frontmatter.

Mode File Structure¶

A mode file has two parts:

1. YAML frontmatter with a mode: section defining metadata and tool policies
2. Markdown body containing the guidance injected into agent context

---
mode:
  name: plan
  description: Planning mode - analysis only, no implementation

  tools:
    safe:
      - read_file
      - grep
      - glob
      - web_fetch
      - LSP
      - delegate
    warn:
      - bash

  default_action: block
---

# Planning Mode

You are in planning mode. Focus on analysis and design, not implementation.

## Guidelines

- Read and explore code freely to build understanding
- Trace call hierarchies and data flows to map architecture
- Identify risks, dependencies, and edge cases
- Produce clear, actionable plans with specific file paths and changes
- Do NOT write, edit, or create any files
- Do NOT execute commands unless absolutely necessary for analysis

Where to Place Mode Files¶

Mode files are discovered from two locations, with project-level modes taking priority:

The file name becomes the mode identifier. A file at .amplifier/modes/review.md creates a mode activated with /mode review.

Writing Effective Mode Guidance¶

The markdown body of your mode file is what the agent actually sees. Write it as clear, direct instructions:

Be explicit about what to do and what not to do:

# Review Mode

You are reviewing code for quality and correctness. Your role is analytical.

## Do
- Read all changed files thoroughly before commenting
- Check for edge cases, error handling, and test coverage
- Provide specific, actionable feedback with line references

## Do Not
- Make any code changes yourself
- Run tests or build commands
- Suggest trivial style changes -- focus on substance

Match tool policies to guidance: If your guidance says "do not modify files," make sure write_file and edit_file are set to block. The guidance and policies should reinforce each other.

Warning: If your guidance says one thing but tool policies allow another, the agent may follow the guidance but the safety net of enforcement is gone. Always align policies with intent.

Designing Tool Policies¶

Think about what the mode needs in terms of capability tiers:

1. Essential tools (safe): Tools the agent must have to fulfill the mode's purpose
2. Occasional tools (warn): Tools the agent might need but should think twice about
3. Dangerous tools (confirm): Tools with significant side effects that need human oversight
4. Prohibited tools (block): Tools that contradict the mode's purpose

For a planning mode:

mode:
  tools:
    safe:
      # Essential: reading and navigation
      - read_file
      - grep
      - glob
      - LSP
    warn:
      # Occasional: might need to check something
      - bash
      - web_fetch

  # Prohibited tools (write_file, edit_file, apply_patch) are
  # caught by the default action -- no need to list them.

  # Default: block anything not listed
  default_action: block

Common Modes¶

Several bundles ship with pre-built modes for common workflows.

Superpowers Bundle¶

Modes Bundle¶

The Deliberate Development bundle provides planning-mode and research-mode as behavioral concepts (context injection via behaviors), but these are not enforced modes with tool policies. They provide guidance without hard tool restrictions.

These pre-built modes encode battle-tested workflows. Use them as-is or as templates for your own custom modes.

Modes vs Other Concepts¶

Understanding how modes relate to other Amplifier concepts:

The key distinction: bundles and tools define capabilities, while modes define constraints. A mode never adds new tools -- it only restricts or guides the use of existing ones.

Practical Patterns¶

The Plan-Execute Pattern¶

The most common mode workflow alternates between planning and execution:

> /mode plan
[plan]> Analyze the payment module and design a refactoring plan

  (agent reads code, traces dependencies, produces a detailed plan)

> /mode off
> /mode execute-plan
[execute-plan]> Implement the refactoring plan from our analysis

  (agent follows the plan, implementing changes systematically)

> /mode verify
[verify]> Verify all changes are correct and tests pass

  (agent runs tests, checks for regressions, confirms completion)

The Investigation Pattern¶

For debugging, modes enforce discipline:

> /mode debug
[debug]> Users are reporting 500 errors on the /api/orders endpoint

  (agent investigates logs, traces code paths, identifies root cause)
  (write tools are restricted -- agent must understand before fixing)

> /mode off
> Fix the issue we identified
  (agent applies the targeted fix with full tool access)

Project-Specific Safety Modes¶

Create modes for sensitive operations in your project:

---
mode:
  name: database
  description: Database work - extra caution with migrations

  tools:
    safe:
      - read_file
      - grep
      - glob
    warn:
      - write_file
      - edit_file
    confirm:
      - bash

  default_action: block
---

# Database Mode

You are working on database schemas and migrations. Exercise extreme caution.

- Always review existing migrations before creating new ones
- Never drop columns or tables without explicit user confirmation
- Test migrations against a local database before suggesting production runs
- Prefer additive changes (add columns) over destructive ones (drop/rename)

Key Takeaways¶

1. Modes are runtime overlays: They modify agent behavior without changing the underlying bundle. Activate and deactivate them freely during a conversation.

2. Tool policies enforce constraints: The four levels (safe, warn, confirm, block) provide graduated control. The default_action catches any tool not explicitly configured.

3. Guidance and policies work together: The markdown body shapes the agent's intent while tool policies provide hard enforcement. Always keep them aligned.

4. Both users and agents can manage modes: Users use slash commands (/mode plan), agents use the mode tool programmatically. Agent-initiated changes go through a warn gate by default.

5. Custom modes are simple to create: A markdown file with YAML frontmatter in .amplifier/modes/ or ~/.amplifier/modes/ is all you need. The file name becomes the mode command.

6. Pre-built modes encode proven workflows: Start with modes from the Superpowers or Deliberate Development bundles before building custom ones.

Related Concepts¶

• Bundles - The capability layer that modes constrain
• Skills - On-demand knowledge injection (complementary to modes)
• Hooks - Observing behavior that modes control
• Recipes - Multi-step workflows that can activate modes per step