Active

Bundle Orchestration

How Amplifier bundles compose, merge, and load — the engine that makes layered agent systems possible

February 2026

The Problem

Configuration Doesn't Compose

🔁

Duplication

Every new project re-declares the same providers, tools, and hooks. No inheritance means no consistency across projects.

💥

Collisions

When two configs define context files with the same name, one silently overwrites the other. No namespacing, no warning.

🧩

No Layering

Want foundation behaviors plus your domain logic? Copy-paste everything. Changes upstream? Copy-paste again.

The Solution

Bundle.compose() — Declarative Layering

A single method on the Bundle dataclass handles all composition. Declare your includes, and the engine merges everything with well-defined rules — 1,347 lines of composition logic.

# Your bundle.yaml
includes:
  - foundation
  - design-intelligence

agents:
  my-agent:
    instruction: "Your domain logic"

# Foundation providers, tools, hooks
# merged in automatically

What compose() Does

Reads the includes list from your bundle
Loads each included bundle recursively
Merges config using 5 distinct strategies
Namespaces context keys to prevent collisions
Returns a single unified Bundle dataclass

How It Works

Five Merge Strategies

Session · Spawn

Deep Merge

Nested dicts merged recursively. Later bundle wins for scalar values. Structure preserved — only leaf values override.

Providers · Tools · Hooks

Merge by Module ID

Each module has a unique ID. Same ID → later config wins. Different IDs → both kept. No silent loss of modules.

Agents

Override by Name

Later bundle's agent definition replaces earlier one with the same name. New names are added to the merged set.

Context

Accumulate + Namespace

Every bundle contributes context files. Keys prefixed with bundle name (foundation:behaviors.md) to avoid collisions.

Instruction

Replace

Later instruction replaces earlier entirely. Your bundle's instruction is the final word — no merging of prose.

Composition Model

Bundles Stack, Not Nest

📦

Your Bundle

Domain agents, custom instruction

↑ compose()

🎨

Domain Bundle

Shared tools, specialized hooks

↑ compose()

🔧

Foundation

Core agents, base providers, behaviors

The Key Insight

Each layer adds capabilities without seeing the layers above. Foundation provides the base. Domain bundles add specialization. Your bundle adds the final instruction and custom agents. compose() flattens this stack into one unified configuration.

Collision Avoidance

Context Namespacing

When bundles compose, each bundle's context keys are automatically prefixed with the bundle name. This prevents silent overwrites when multiple bundles define files with the same name.

# Before compose — collision risk
foundation/context/behaviors.md
stories/context/behaviors.md

# After compose — namespaced
foundation:context/behaviors.md
stories:context/behaviors.md

# Both preserved, zero collision

Why This Matters

No silent data loss — every bundle's context survives composition
Predictable resolution — namespace tells you which bundle owns what
Safe evolution — bundles add files without breaking others
source_base_paths tracking — each namespace maps back to its source directory for @mention resolution

Development

By the Numbers

1,347

Lines in bundle.py

wc -l bundle.py

317

Foundation Commits

git log --oneline | wc -l

~94%

Single-Author Share

Brian Krabach: 299/317

Primary contributor: Brian Krabach (299 commits, ~94.3%). Additional contributors: Samuel Lee (8), Marc Goodner (5), Diego Colombo (4).

Sources

Research Methodology

Data as of: February 20, 2026

Feature status: Active — bundle composition is the core loading mechanism in amplifier-foundation

Repository: amplifier-foundation (local clone)

Research performed:

File discovery: find . -name "bundle.py" -path "*/amplifier_foundation/*" → 1 file
Line count: wc -l amplifier_foundation/bundle.py → 1,347 lines
Composition logic: grep -n "compose|merge|include" bundle.py → 30+ matches analyzed
Merge rules: grep -n "deep.*merge|replace|accumulate" bundle.py → 10 matches
Source reading: sed -n '95,215p' bundle.py — full compose() method verified
Commit count: git log --oneline | wc -l → 317
Contributors: git log --format="%an" | sort | uniq -c | sort -rn → 5 entries (incl. bot)

Gaps: PR-level data not queried. Merge strategy descriptions from source code docstrings and comments, not runtime testing. Bundle loading performance not measured.

Primary contributor: Brian Krabach — 299 of 317 commits (~94.3%)

Get Started

Try Bundle Composition

Add includes: [foundation] to your bundle.yaml and inherit the entire foundation layer — providers, tools, hooks, agents, and behaviors.

amplifier-foundation · bundle.py · 1,347 lines of composition logic