Developer Guide

Best Practices
& Patterns

Verified patterns from the Amplifier Foundation codebase

Active

February 2026

The Problem

Without patterns, agents get messy

📦

Fat Bundles

Redeclaring tools, session config, and hooks that foundation already provides. Duplication creates maintenance burden and version conflicts.

🧠

Context Explosion

Loading entire repos into context, passing full history to every sub-agent. Wastes tokens, degrades quality.

🔧

Vague Agents

Agent descriptions that say "helps with code stuff." No activation triggers, no examples. Coordinators can't route work.

            The foundation repo contains 488 lines of documented patterns in PATTERNS.md and 1,314 lines in BUNDLE_GUIDE.md. These aren't abstract advice — they're extracted from production use across 317 commits.
        

Pattern #1

The Thin Bundle Pattern

The single most important pattern in the ecosystem

❌ Fat Bundle

Redeclares session, tools, hooks that foundation already provides. Creates maintenance burden and misses foundation updates.

✅ Thin Bundle

Includes foundation, adds only what's unique. Inherits all tools, session config, hooks automatically.

# Thin bundle — only 14 lines of YAML
bundle:
  name: my-capability
  version: 1.0.0

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main

# That's it. All tools and hooks come from foundation.

Pattern #2

Three composition strategies

🏗️

Base + Environment

Layer environment-specific config over a shared base. Dev gets debug mode, prod gets timeouts. Use base.compose(overlay).

🔗

Includes Chain

Declarative layering with includes: in YAML. Each bundle references its parent. Later values override earlier ones.

🧩

Feature Bundles

Compose features additively: base.compose(filesystem_tools, web_tools). Add exactly the capabilities you need.

            Merge rules are section-specific: Session and spawn deep-merge. Providers, tools, and hooks merge by module ID (same ID = update config, new ID = add). Instructions replace entirely — later wins.
        

Pattern #3

Agents are bundles

The Key Insight

Agents use the same file format as bundles. The only difference is the frontmatter key: meta: instead of bundle:. Both are loaded via load_bundle().

Description = Advertisement

The meta.description field is how coordinators decide which agent to delegate to. Answer three questions: WHEN to use it, WHAT it does, HOW to invoke it (with examples).

# Good agent description pattern (from AGENT_AUTHORING.md)
meta:
  name: bug-hunter
  description: |
    Specialized debugging expert. Use PROACTIVELY when
    user reports errors or test failures.

    Examples:
    <example>
    user: 'The pipeline is throwing a KeyError'
    assistant: 'I'll use bug-hunter to track this down.'
    </example>

Pattern #4

Context discipline

✓ Targeted reads — Use grep and glob to find, then read specific files
✓ Sub-agents get focused context — Use context_depth: "none" for clean slate, "recent" for last N turns
✓ @mention resolution — Reference context files across bundles: @foundation:context/guidelines.md
✓ Tool inheritance control — Use exclude_tools or inherit_tools in tool-task config to control what agents can do
✓ Prepare once, execute many — Call bundle.prepare() once, create multiple sessions from it

            Common pattern: Prevent infinite delegation chains with exclude_tools: [tool-task]. Spawned agents do the work themselves rather than trying to spawn sub-agents.
        

Pattern #5

Validate before you ship

✅

Bundle Validation

Use validate_bundle_or_raise(bundle) before prepare. Catches missing sections, invalid configs. Extend with custom rules via BundleValidator.

🧪

Mock Providers

Use provider-mock in tests with predefined responses. No API calls, deterministic results. Test your bundle logic without LLM costs.

🌑

Shadow Environments

Test multi-repo changes in isolation. The amplifier-dev bundle includes shadow environment support for testing core + foundation together.

What Not to Do

Anti-patterns from real usage

✗ Fat bundles — Redeclaring what foundation provides. Include it, don't copy it.
✗ Vague agent descriptions — "Helps with code stuff" gives coordinators nothing to work with.
✗ Context dumping — Loading 50 files "just in case." Let sub-agents fetch what they need.
✗ Skipping validation — Deploying bundles without validate_bundle_or_raise(). Errors surface at runtime.
✗ Ignoring merge rules — Expecting instructions to merge when they actually replace. Know the rules per section.

The Pattern Library

Built from production experience

317

Commits in foundation

10

Documentation guides

~94%

Commits by Brian Krabach

            Documentation includes: PATTERNS.md (488 lines), BUNDLE_GUIDE.md (1,314 lines), AGENT_AUTHORING.md, CONCEPTS.md, API_REFERENCE.md, DOMAIN_VALIDATOR_GUIDE.md, POLICY_BEHAVIORS.md, PR_REVIEW_GUIDE.md, URI_FORMATS.md, ISSUE_CASE_STUDIES.md. First commit Dec 9, 2025; latest Feb 10, 2026.
        

Sources

Research Methodology

Data as of: February 20, 2026

Feature status: Active

Repository: microsoft/amplifier-foundation (local clone)

Research performed:

Commit count: git log --oneline | wc -l → 317 commits
Contributors: git log --format="%an" | sort | uniq -c | sort -rn → Brian Krabach (299), Samuel Lee (8), Marc Goodner (5), Diego Colombo (4), dependabot[bot] (1)
Docs listing: ls docs/ → 10 documentation files
Pattern lines: wc -l docs/PATTERNS.md → 488 lines
Bundle guide lines: wc -l docs/BUNDLE_GUIDE.md → 1,314 lines
Example files: find examples -type f | wc -l → 902 files
Bundle configs: ls bundles/ → 4 files (amplifier-dev.yaml, minimal.yaml, with-anthropic.yaml, with-openai.yaml)
Commit date range: git log --format="%ai" → Dec 9, 2025 to Feb 10, 2026
Pattern verification: Read PATTERNS.md, BUNDLE_GUIDE.md, AGENT_AUTHORING.md, CONCEPTS.md in full

Gaps: Example files count (902) includes .venv dependencies — actual authored examples are fewer. Exact number of authored examples not isolated.

Primary contributor: Brian Krabach (~94% of commits, 299 of 317)

Get Started

Learn the patterns

Start with PATTERNS.md. Build thin bundles. Validate early.

Pattern Guide: amplifier-foundation/docs/PATTERNS.md
Bundle Guide: amplifier-foundation/docs/BUNDLE_GUIDE.md
Agent Authoring: amplifier-foundation/docs/AGENT_AUTHORING.md
Core Concepts: amplifier-foundation/docs/CONCEPTS.md

Best Practices& Patterns