Bundle Fundamentals

Bundles are the foundation of Amplifier's configuration system. Understanding how they work is essential to using and extending Amplifier effectively.

What is a Bundle?

A bundle is a markdown file with YAML frontmatter that packages:

• Configuration - Which modules to load (providers, tools, hooks, orchestrators)
• Resources - Context files, agent definitions, examples
• Composition - References to other bundles to include
• Instructions - System prompts and documentation in markdown

Anatomy of a Bundle

---
bundle:
  name: my-bundle
  version: 1.0.0
  description: What this bundle does

includes:
  - bundle: foundation  # Inherit from foundation bundle

providers:
  - module: provider-anthropic
    source: git+https://github.com/microsoft/amplifier-module-provider-anthropic@main
    config:
      default_model: claude-sonnet-4-5

tools:
  - module: tool-custom
    source: git+https://github.com/you/tool-custom@main

hooks:
  - module: hooks-logging
    source: git+https://github.com/microsoft/amplifier-module-hooks-logging@main

agents:
  - agent: my-expert

context:
  - file: context/instructions.md
---

# System Instructions

Your system prompt and documentation goes here in markdown.

This content becomes part of the agent's context.

## Using @mentions

You can reference other files:

@my-bundle:context/domain-knowledge.md

Key Concepts

Bundle Composition with includes:

Bundles can include other bundles, creating a composable stack:

includes:
  - bundle: foundation           # Base capabilities
  - bundle: lsp                  # Add LSP support
  - bundle: my-bundle:behaviors/notifications  # Behavior overlay

When bundles are included:

• Their modules are merged (later overrides earlier)
• Their agents are combined
• Their context is accessible via @mentions
• Their system instructions are composed

Module Sources

Each module in a bundle must specify where to find it:

• git+https://github.com/owner/repo@branch - Git repository
• file:///absolute/path - Local filesystem
• ./relative/path - Relative to bundle location

The foundation bundle handles downloading and activating module sources automatically.

@mentions and Namespaces

Bundles create namespaces for referencing resources:

# From within a bundle's markdown:
@my-bundle:context/instructions.md      # File in this bundle
@foundation:context/shared/base.md      # File in foundation bundle
@lsp:agents/code-navigator.md           # Agent from LSP bundle

Why Bundles Replace Profiles/Collections

Bundle Types

Foundation Bundles

Core bundles that provide base functionality. Most custom bundles will include foundation as their starting point.

Domain Bundles

Specialized bundles for specific use cases: recipes (workflow orchestration), design-intelligence (design system work), lsp (code intelligence).

Behavior Bundles

Small bundles that add specific behaviors via hooks. These are often included by other bundles rather than used directly.

Extension Bundles

Bundles that extend other bundles. Example: lsp-python extends lsp with Python-specific capabilities.

How Bundles are Loaded

Applications load bundles and compile them into mount plans:

1. Bundle file is read (local file or downloaded from git)
2. YAML frontmatter is parsed
3. Included bundles are loaded recursively
4. Module sources are resolved and downloaded
5. Mount plan is compiled (providers/tools/hooks/orchestrator/context)
6. Resources are made available via @mention system
7. Session is created with the mount plan

Next Steps

• Learn about bundle composition patterns
• Create your own bundle
• Browse available bundles
• Deep dive into all bundles