Bundle Composition Patterns

One of the most powerful features of bundles is composition - the ability to build complex configurations by combining simpler bundles. This page explores real-world composition patterns from the Amplifier ecosystem.

The includes: Mechanism

Bundles can include other bundles using the includes: field:

---
bundle:
  name: my-bundle
  version: 1.0.0

includes:
  - bundle: foundation                    # From registry or git
  - bundle: git+https://github.com/...   # Explicit git URL
  - bundle: my-bundle:behaviors/extra    # Subdirectory reference
---

When a bundle is included, its entire configuration merges into the parent:

Pattern: Base + Extension

The most common pattern: extend a base bundle with domain-specific capabilities.

Example: LSP Python

The lsp-python bundle extends lsp:

---
bundle:
  name: lsp-python
  version: 1.0.0
  description: Python code intelligence via Pyright

includes:
  - bundle: lsp  # Get all base LSP functionality

tools:
  - module: tool-lsp-client
    config:
      language_servers:
        - name: pyright
          command: pyright-langserver
          args: ["--stdio"]

agents:
  - agent: python-code-intel
    file: agents/python-code-intel.md
---

# Python Code Intelligence

@lsp-python:context/python-capabilities.md

What this achieves:

Pattern: Layered Behaviors

Build up functionality by layering behavior bundles.

Example: Custom Stack

---
bundle:
  name: my-production-setup
  version: 1.0.0

includes:
  - bundle: foundation                    # Base tools/providers
  - bundle: notify:behaviors/desktop      # Add desktop notifications
  - bundle: issues:behaviors/tracking     # Add issue tracking
  - bundle: my-custom:behaviors/logging   # Custom logging rules

providers:
  - module: provider-anthropic
    config:
      default_model: claude-opus-4-1  # Override for production
---

# Production Assistant

@my-production-setup:context/production-guidelines.md

Each layer adds:

Pattern: Bundle Families

Create a family of related bundles with shared base.

Example: Development Environments

# bundles/base.md - Shared foundation
---
bundle:
  name: my-company-base
  version: 1.0.0

includes:
  - bundle: foundation

tools:
  - module: tool-company-internal
    source: git+https://github.com/company/tool@main

context:
  - file: context/company-standards.md
---

@my-company-base:context/company-standards.md

# bundles/python-dev.md - Python-specific
---
bundle:
  name: my-company-python
  version: 1.0.0

includes:
  - bundle: ./base.md         # Inherit company base
  - bundle: lsp-python        # Add Python LSP

agents:
  - agent: python-reviewer
---

Python development with company standards

# bundles/typescript-dev.md - TypeScript-specific
---
bundle:
  name: my-company-typescript
  version: 1.0.0

includes:
  - bundle: ./base.md           # Same company base
  - bundle: lsp-typescript      # Add TypeScript LSP

agents:
  - agent: typescript-reviewer
---

TypeScript development with company standards

Pattern: Behavior Composition

Small bundles that just add hooks or behaviors, designed to be composed.

Example: Notification Behaviors

# behaviors/desktop-notifications.yaml (small bundle)
---
bundle:
  name: notify-desktop
  version: 1.0.0

hooks:
  - module: hooks-notify
    source: git+https://github.com/microsoft/amplifier-bundle-notify@main#subdirectory=modules/hooks-notify
    config:
      method: desktop
---

Use it in any bundle:

includes:
  - bundle: foundation
  - bundle: notify-desktop  # Just add notifications

Pattern: Environment-Specific Overrides

Different bundles for dev/staging/production:

# bundles/dev.md
---
bundle:
  name: app-dev
  version: 1.0.0

includes:
  - bundle: ./base.md

providers:
  - module: provider-anthropic
    config:
      default_model: claude-sonnet-4-5  # Cheaper for dev
---

# bundles/production.md
---
bundle:
  name: app-production
  version: 1.0.0

includes:
  - bundle: ./base.md

providers:
  - module: provider-anthropic
    config:
      default_model: claude-opus-4-1  # More capable for prod

hooks:
  - module: hooks-approval  # Extra safety in production
---

Composition Tips

Include order matters
Later includes override earlier ones. Put base bundles first, customizations last.
Keep behavior bundles small
Single-responsibility bundles are more reusable. A bundle that just adds notifications can be composed anywhere.
Use relative includes for bundle families
When creating multiple related bundles, use ./base.md relative paths so they stay together.

Real Examples from the Ecosystem

Bundle Pattern What it demonstrates
lsp-python Base + Extension Extends lsp with Python-specific agent and config
lsp-typescript Base + Extension Extends lsp with TypeScript-specific agent and config
design-intelligence Domain Bundle 7 specialized agents, design framework, knowledge base
recipes Orchestration Multi-step workflows with behavior overlays
foundation Base The foundation most bundles build on

Next Steps