Understanding Bundles¶

Bundles are the fundamental unit of composition in Amplifier. They package capabilities, behaviors, and configuration into reusable, shareable units that can be combined to create powerful AI-powered applications.

What is a Bundle?¶

A bundle is a composable configuration package that defines what an AI assistant can do. Think of bundles like LEGO sets—each one provides specific pieces that snap together with other bundles to build complete solutions.

Core Characteristics¶

Bundles share several defining characteristics:

1. Self-contained: Each bundle includes everything it needs to function
2. Composable: Bundles can include other bundles to build on existing capabilities
3. Declarative: Configuration is specified in YAML, not imperative code
4. Portable: Bundles can be shared, versioned, and distributed independently

What Bundles Contain¶

A typical bundle may include:

• Configuration: YAML frontmatter defining metadata and settings
• Instructions: Markdown content providing guidance to the AI
• Behaviors: References to specific capabilities or tools
• Context files: Supporting documentation and examples
• Includes: References to other bundles to compose functionality

The Thin Bundle Pattern¶

Amplifier follows the "thin bundle" philosophy -- bundles should be thin configuration layers, not monolithic files. In practice, a well-structured bundle.md is mostly YAML frontmatter that points to includes and @mentions. The actual content lives in separate files that are referenced, not inlined.

A well-designed bundle:

• References behaviors instead of duplicating logic
• Includes foundation bundles for common capabilities
• Adds only the specific instructions needed for its use case
• Stays focused on a single domain or purpose
• Keeps heavy context in external files referenced via @mentions

Here is what a thin bundle looks like in practice:

---
bundle:
  name: team-python-dev
  version: "1.0.0"

includes:
  - bundle: foundation
  - bundle: python-dev:behaviors/python-dev
  - bundle: team-python-dev:behaviors/code-review
  - bundle: team-python-dev:behaviors/testing

context:
  include:
    - ./standards/python-style.md
    - ./standards/testing-policy.md
---

# Team Python Development

Follow the coding standards in @standards/python-style.md and the testing
policy in @standards/testing-policy.md when working on this project.

## Project-Specific Notes

- Use `pytest` for all test files.
- Database migrations live in `src/migrations/`.

The bundle file itself is small. The substance lives in the referenced files -- python-style.md, testing-policy.md, and the included bundles. This is the pattern to follow.

Bundle Structure¶

Every bundle consists of a markdown file with YAML frontmatter. The frontmatter defines the bundle's metadata and configuration, while the markdown body provides instructions and context for the AI.

Anatomy of a Bundle File¶

---
bundle:
  name: my-custom-bundle
  version: 1.0.0
  description: A bundle that does something useful

# Include other bundles and behaviors
includes:
  - bundle: foundation
  - bundle: my-custom-bundle:behaviors/code-review
  - bundle: my-custom-bundle:behaviors/testing
---

# My Custom Bundle

Instructions for the AI go here in markdown format.

## What This Bundle Does

Explain the purpose and capabilities...

## How to Use

Provide guidance on usage patterns...

Frontmatter Fields¶

Required Fields¶

Common Optional Fields¶

Markdown Body¶

The markdown body serves as the primary instruction set for the AI. Write clear, actionable guidance that helps the AI understand:

• What the bundle is designed to do
• How to approach tasks within its domain
• What patterns and practices to follow
• What to avoid or be careful about

context.include vs @mentions¶

These two mechanisms both bring external content into a bundle, but they have different semantics. Confusing them is a common source of errors.

context.include -- structural composition at bundle load time:

context:
  include:
    - ./standards/python-style.md
    - ./standards/testing-policy.md

Files listed under context.include are added to the bundle's context section during composition. They become part of the bundle's resolved configuration. This is a build-time operation -- the files are loaded and merged when the bundle is assembled, before any conversation begins.

@mentions -- inline references resolved at render time:

Follow the coding standards in @standards/python-style.md when reviewing code.

An @mention in the markdown body is resolved when the content is rendered into the AI's context window. It acts as an inline expansion -- the referenced file's content replaces the @mention at the point where it appears in the text.

When to use which:

In practice, thin bundles use context.include for files that define the bundle's capabilities and @mentions in the markdown body for files the AI should consult while working. Both can reference the same file -- they are not mutually exclusive, but they serve different purposes.

Composition¶

Composition is where bundles become powerful. Instead of building monolithic configurations, you compose small, focused bundles into complete solutions.

The includes Field¶

The includes field specifies which bundles to incorporate:

includes:
  - bundle: foundation                  # Foundation capabilities
  - bundle: foundation:git-ops          # Git operations
  - bundle: my-org:behaviors/standards  # Organization standards

Include Resolution¶

Bundles are resolved using a namespace:name pattern:

• foundation:core → Built-in foundation bundle
• my-collection:my-bundle → Bundle from a custom collection
• ./local-bundle → Relative path to a local bundle file

Composition Order¶

When multiple bundles are composed, they're processed in order:

1. Base bundles (from includes) are loaded first
2. Each included bundle's includes are resolved recursively
3. The current bundle's configuration is applied last
4. Later configurations can override earlier ones

Behaviors¶

Behaviors are reusable capability packages that bundles can include. The term "behavior" is a naming convention, not a code construct -- a behavior is just a bundle that provides a focused set of capabilities intended to be composed into other bundles. Behaviors are included via the includes: field, using the - bundle: prefix and a path into the behavior's directory:

includes:
  - bundle: my-bundle:behaviors/code-review      # Code review capabilities
  - bundle: my-bundle:behaviors/testing          # Testing capabilities
  - bundle: my-bundle:behaviors/documentation    # Documentation generation

Behaviors are bundles themselves. A behavior might declare its own tools, agents, and context. Including a behavior merges those declarations into the parent bundle.

Policy Behaviors¶

Some behaviors should only take effect in the root session, not in sub-agent sessions. These are called policy behaviors. A common example: a notification behavior should fire when the root session completes a task, but not when every sub-agent finishes its work.

Policy behaviors check parent_id to determine whether they are running at the root level:

If parent_id is set, this is a sub-agent session -- skip policy behavior.
If parent_id is not set, this is the root session -- apply policy behavior.

This prevents cascading side effects. Notifications, logging to external systems, and approval gates are typical policy behaviors that should only run at the root.

Spawn Policy¶

Bundles can configure a spawn policy that controls how agents are spawned from the bundle's session. This governs tool inheritance and exclusion:

spawn:
  exclude_tools:
    - tool-dangerous-thing     # Prevent sub-agents from using this tool

Spawn policy is how you enforce boundaries between the parent session and its delegated agents. For example, you might want sub-agents to have file read access but not write access, or you might exclude tools that interact with external services to prevent unintended side effects from parallel agent execution.

Practical Composition Example¶

Here's how you might compose a code review bundle:

---
bundle:
  name: team-code-review
  version: 1.0.0

includes:
  - bundle: foundation
  - bundle: foundation:git-ops
  - bundle: team-code-review:behaviors/code-review
  - bundle: team-code-review:behaviors/security-review
---

# Team Code Review

Use this bundle when reviewing pull requests for our team.

## Review Checklist

1. Check for security vulnerabilities
2. Verify test coverage
3. Ensure code follows our style guide
4. Look for performance issues

## Our Standards

- All functions must have docstrings
- Maximum cyclomatic complexity: 10
- No hardcoded secrets

Creating a Bundle¶

Follow these steps to create your own bundle.

Step 1: Define the Purpose¶

Before writing any configuration, clearly define:

• What problem does this bundle solve?
• Who will use it?
• What capabilities does it need?
• What existing bundles can it build on?

Step 2: Choose Your Base¶

Start by identifying which foundation bundles to include:

includes:
  - bundle: foundation    # Almost always needed

Add additional foundations based on your needs:

• foundation:file-ops for file manipulation
• foundation:git-ops for version control
• foundation:web-research for internet access

Step 3: Write the Frontmatter¶

Create your bundle file with appropriate metadata:

---
bundle:
  name: my-project-helper
  version: 1.0.0
  description: Helps with tasks specific to my project

includes:
  - bundle: foundation
  - bundle: my-project-helper:behaviors/testing
---

Step 4: Write Instructions¶

Add clear, specific instructions in the markdown body:

# My Project Helper

You help developers work on the MyProject codebase.

## Project Structure

- `src/` - Source code
- `tests/` - Test files
- `docs/` - Documentation

## Coding Standards

- Use TypeScript strict mode
- Write tests for all public functions
- Follow the error handling patterns in `src/utils/errors.ts`

## Common Tasks

### Adding a New Feature
1. Create a branch from main
2. Implement the feature in `src/features/`
3. Add tests in `tests/features/`
4. Update documentation if needed

Step 5: Test Your Bundle¶

Test your bundle by running Amplifier with it:

amplifier run --bundle ./my-bundle.md "Test my bundle"

Verify that:

• All includes resolve correctly
• The AI understands your instructions
• Tools and capabilities work as expected

Step 6: Iterate and Refine¶

Based on testing, refine your bundle:

• Add missing instructions
• Remove unnecessary includes
• Clarify ambiguous guidance
• Add examples for complex tasks

Best Practices¶

Keep Bundles Focused¶

Each bundle should have a clear, singular purpose. If you find yourself adding unrelated capabilities, consider splitting into multiple bundles.

Use Semantic Versioning¶

Version your bundles to track changes:

• Major: Breaking changes to behavior or structure
• Minor: New capabilities, backward compatible
• Patch: Bug fixes and documentation updates

Document Your Bundles¶

Include clear documentation in the markdown body:

• What the bundle does
• How to use it effectively
• What it doesn't do (scope boundaries)
• Examples of common tasks

Leverage Composition¶

Don't duplicate functionality. If another bundle provides what you need, include it rather than recreating it.

Test with Real Scenarios¶

Validate your bundle with actual use cases, not just theoretical ones. Real-world testing reveals gaps in instructions and missing capabilities.

Anti-Patterns to Avoid¶

These are common mistakes that lead to bundles that are hard to maintain, slow to load, or confusing to compose.

Monolithic Bundles¶

Putting everything into a single bundle file -- instructions, context, standards, tool configuration -- defeats the purpose of composition. If your bundle file is hundreds of lines long, it should be broken into smaller bundles and composed with includes.

Instead: Split into focused bundles. One for coding standards, one for tool configuration, one for project-specific instructions. Compose them together.

Inline Heavy Context¶

Pasting large blocks of reference material directly into the bundle's markdown body wastes context window space and makes the bundle hard to update.

Instead: Put reference material in separate files and use @mentions to pull them in. This keeps the bundle thin and the reference material independently editable.

Confusing context.include with @mentions¶

Using context.include when you mean @mention (or vice versa) leads to content appearing in the wrong place or being loaded twice. See the context.include vs @mentions section above for the distinction.

Root pyproject.toml in Bundles¶

Bundles are not Python packages. Adding a pyproject.toml at the bundle root introduces confusion about what the bundle is and how it should be installed. Bundles are resolved by the Amplifier composition system, not by pip.

Not Using Behaviors for Reusable Capability Sets¶

If you find yourself copying the same set of tools, instructions, and context across multiple bundles, that shared capability should be extracted into a behavior. Behaviors exist precisely to avoid this duplication.

Instead: Create a behavior bundle for the shared capability, then include it with includes: in each bundle that needs it.

Key Takeaways¶

1. Bundles are composable packages that define AI assistant capabilities through declarative YAML configuration and markdown instructions. Bundle files use bundle: frontmatter with name and version.

2. Thin bundles are the goal: A bundle.md should be mostly YAML frontmatter pointing to includes and @mentions. Heavy content belongs in external files.

3. context.include and @mentions are different: context.include is structural composition at bundle load time. @mentions are inline references resolved at render time. Know which one you need.

4. Composition over duplication: Build on existing bundles using includes rather than recreating functionality.

5. Behaviors are reusable capability packages: Extract shared tool/instruction sets into behaviors rather than copying them across bundles.

6. Policy behaviors respect session hierarchy: Behaviors with side effects (notifications, external logging) should check parent_id and only run at the root session level.

7. Spawn policy controls delegation boundaries: Use spawn: to configure which tools sub-agents inherit or are excluded from using.

8. Avoid the anti-patterns: Monolithic bundles, inline heavy context, root pyproject.toml files, and confusing include mechanisms are the most common mistakes.

9. Start minimal, test iteratively: Begin with the smallest set of includes and behaviors needed, then add more as requirements emerge. Validate with real use cases.

Bundles embody Amplifier's philosophy of modular, composable design. By creating well-structured, thin bundles, you build reusable capabilities that can be shared across projects and teams, enabling consistent AI-powered workflows wherever they are needed.