amplifier-bundle-modes

A generic mode system for Amplifier that enables runtime behavior modification through user-defined modes.

Overview

Modes are lightweight runtime overlays that modify assistant behavior without changing the underlying bundle configuration. When a mode is active:

1. Context injection - Mode-specific guidance is injected into each turn
2. Tool moderation - Tools are allowed, warned, confirmed, or blocked based on mode policy
3. Visual indicator - Prompt shows [mode]> when active

Quick Start

> /mode plan
Mode: plan — Analyze, strategize, and organize - but don't implement

[plan]> analyze the authentication flow

... assistant explores and discusses without modifying files ...

[plan]> /mode off
Mode off: plan

> now implement the changes

Built-in Modes

Any mode can be overridden by placing a file with the same name: value in a higher-precedence location:

• Project-level override: .amplifier/modes/ in the project root
• User-level override: ~/.amplifier/modes/ in your home directory

Mode	Shortcut	Description	Advertised to LLM
plan	/plan	Analyze, strategize, and organize — no implementation	Yes
careful	/careful	Full capability with confirmation for destructive actions	Yes
explore	/explore	Zero-footprint codebase exploration — read-only	Yes
mode-design	/mode-design	Design a new Amplifier mode through structured authoring	No — hidden from LLM; activate via slash command

Modes with advertised: false

mode-design carries advertised: false in its frontmatter. This means:

• The LLM does not see it in the mode(list) tool output, so it will not spontaneously suggest or list it.
• It does appear in the human-facing /modes listing (marked (hidden)), and its slash command /mode-design is fully registered.

Activating /mode-design materializes three artifacts into the session:

Artifact	Type	Purpose
mode-author	Agent	Drafts complete mode .md files from a brief intent statement
mode-design-discipline	Skill	Anti-bloat patterns, naming hygiene, narration rules
mode-schema-reference.md	Context	Full mode YAML schema injected into every turn

All three materialize on activation and disappear on deactivation. Sessions that never activate /mode-design see none of those artifacts.

Tool Policies

Modes control tool access through policies:

Policy	Behavior
safe	Tool works normally
warn	Blocked once with warning; retry proceeds
confirm	Requires user approval via approval hook
block	Tool disabled entirely

Approval Integration

The confirm policy integrates with the approval hook system. When a tool is marked confirm, the mode hook sets it up for approval, and the approval hook prompts the user before execution.

This is used by careful mode for write operations (write_file, edit_file, bash).

Creating Custom Modes

Authoring with mode-design

The fastest way to author a new mode is to activate /mode-design:

/mode-design

This mode contributes the mode-author agent, the mode-design-discipline skill, and the full schema reference. Together they guide you through intent statement → tool policy → body draft in a single session. The full schema reference is at context/mode-schema-reference.md, reachable as @modes:context/mode-schema-reference.md or injected automatically when /mode-design is active.

Authoring by hand

Create a markdown file with YAML frontmatter:

---
mode:
  name: cautious
  description: Ask before any destructive action
  shortcut: cautious   # Optional; defaults to `name`. Use `shortcut: false` to disable.
  
  tools:
    safe:
      - read_file
      - grep
      - glob
    warn:
      - bash
    confirm:
      - write_file
      - edit_file
  
  default_action: block
---

CAUTIOUS MODE: Confirm before any changes.

Before using any tool that modifies state:
1. Explain what you intend to do
2. Wait for user confirmation
3. Then proceed

Do NOT make changes without explicit approval.

Mode File Locations

Modes are discovered from (highest precedence first):

1. <project>/.amplifier/modes/ - Project-specific modes
2. ~/.amplifier/modes/ - User-defined modes
3. Bundle modes/ directory - Built-in modes from this bundle
4. Config search_paths entries - Explicit additional paths
5. Composed bundle modes/ directories - Auto-discovered from all bundles in the session

Note: In server/web deployments, "project" is determined by the session.working_dir capability, not the server process cwd. This enables correct mode discovery when Amplifier runs as a backend service.

Known Limitations

CLI command name conflicts: Modes named the same as built-in CLI commands (help, mode, modes, exit, quit) will have their default /<name> slash alias silently overridden by the CLI's built-in command dispatch. These modes remain activatable via /mode <name>. To give such a mode a working slash alias, set shortcut: explicitly to a non-reserved value.

Opt-out syntax note: shortcut: false (YAML boolean, unquoted) disables the alias. shortcut: "false" (quoted string) is a shortcut literally named false and registers /false. Use the unquoted boolean form to disable.

Third-Party Bundle Modes

Any bundle that includes hooks-mode can contribute custom modes by placing .md files in a modes/ directory at the bundle root. These are auto-discovered at runtime — no special configuration needed beyond the directory convention.

Naming guidance for third-party bundle authors: Use descriptive, unique names (e.g. systems-design rather than design, perf-audit rather than perf). First-load wins silently on shortcut collision; the second bundle's shortcut is dropped with an INFO log. If two modes claim the same shortcut key, the one discovered first (based on search-path precedence) wins; the other can still be activated via /mode <name>.

Example bundle structure:

my-bundle/
├── bundle.md
├── modes/
│   ├── my-custom-mode.md    # Automatically discovered
│   └── another-mode.md
└── ...

The bundle's bundle.md just needs to include hooks-mode:

hooks:
  - module: hooks-mode
    source: git+https://github.com/microsoft/amplifier-bundle-modes@main#subdirectory=modules/hooks-mode

All modes from all composed bundles appear in /modes and are activatable via /mode <name> or shortcuts.

Mode Configuration

Field	Required	Description
name	Yes	Mode identifier
description	No	Shown when mode activates
shortcut	No (defaults to name)	Slash-command alias. Defaults to the mode's name (lowercased). Set to false to disable. Must match ^[a-z][a-z0-9_-]*$ after lowercasing; invalid values log a warning and register no alias.
tools.safe	No	Tools always allowed
tools.warn	No	Tools that warn once, then allow
tools.confirm	No	Tools that require user approval
tools.block	No	Tools explicitly blocked
default_action	No	block (default) or allow for unlisted tools

Commands

Command	Action
/mode <name>	Toggle mode on/off
/mode <name> on	Explicit activate
/mode <name> off	Explicit deactivate
/mode off	Clear any active mode
/modes	List available modes
/<mode-name>	Auto-generated shortcut for each mode (use shortcut: false to disable, or set shortcut: to override)

Architecture

amplifier-bundle-modes/
├── bundle.md                    # Thin bundle wrapper
├── behaviors/
│   └── modes.yaml               # Hooks configuration
├── modes/                       # Built-in mode definitions
│   ├── explore.md
│   ├── plan.md
│   ├── careful.md
│   └── mode-design.md           # advertised:false — human-only slash command
├── modules/
│   ├── hooks-mode/              # Generic mode hook module
│   │   ├── pyproject.toml
│   │   └── amplifier_module_hooks_mode/
│   │       └── __init__.py
│   └── tool-mode/               # LLM-facing mode(list/set/clear) tool
│       ├── pyproject.toml
│       └── amplifier_module_tool_mode/
│           └── __init__.py
├── context/
│   └── modes-instructions.md    # Agent-facing context
└── README.md

How It Works

1. Mode Discovery: ModeDiscovery searches paths for .md files
2. Mode Loading: parse_mode_file() extracts YAML config + markdown context
3. Context Injection: provider:request hook injects mode's markdown as <system-reminder>
4. Tool Moderation: tool:pre hook checks each tool against mode's policy
5. Approval Integration: confirm tools are delegated to approval hook via require_approval_tools

Integration

Include in your bundle:

includes:
  - bundle: foundation
  - bundle: modes

The mode system hooks will automatically register and begin discovering modes.

Philosophy

Modes embody Amplifier's "mechanism not policy" principle:

• Bundle provides mechanism - Generic hooks, discovery, moderation
• Mode files provide policy - Tool lists, context, behavior
• App provides toggle - /mode command, prompt indicator
• Users customize freely - Create modes without writing code

License

MIT

Contributing

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.