AGENTS.md: is it special?

Short answer: AGENTS.md is not a kernel-level "magic file" in Amplifier. It becomes effectively special because the foundation bundle includes instructions that reference it via the @mention mechanism, and the bundle system automatically expands @mentions when loading bundle content.

What “special” would mean (and what it doesn’t)

There is no code in amplifier-core that says “always load AGENTS.md”. The kernel has no file-name constant for it and no dedicated loader. The core contract is: apps can inject system/developer messages any way they want.

What is special (in practice)
The foundation bundle's instruction set tells the model that AGENTS.md is an anchor for behavioral rules, and it includes @mentions that point at likely locations for that file. When those mentions resolve, the bundle system includes the file's content in the system message.

The Complete Loading Chain

Here's exactly how AGENTS.md gets loaded when you use the foundation bundle:

  1. Foundation bundle (bundle.md) includes @foundation:context/shared/common-system-base.md
  2. common-system-base.md (source) includes @foundation:context/shared/common-agent-base.md
  3. common-agent-base.md (source) contains the AGENTS.md references:
    • @~/.amplifier/AGENTS.md (global user config)
    • @.amplifier/AGENTS.md (project config)
    • @AGENTS.md (root of working directory)
  4. @mention resolver (resolver.py) resolves these to actual file paths
  5. MentionLoader (loader.py) loads the files recursively
  6. Bundle system (bundle.py) assembles all content into the system message

Where AGENTS.md is Referenced

The exact location in the source code (line 112-114 of common-agent-base.md):

# AGENTS files

There may be any of the following files that are accessible to be loaded into your context:

- @~/.amplifier/AGENTS.md
- @.amplifier/AGENTS.md
- @AGENTS.md

This appears in amplifier-foundation/context/shared/common-agent-base.md

What Each Reference Means

Reference Resolves To Purpose
@~/.amplifier/AGENTS.md ~/.amplifier/AGENTS.md Global user configuration (applies to all projects)
@.amplifier/AGENTS.md ./amplifier/AGENTS.md (relative to CWD) Project-specific configuration
@AGENTS.md ./AGENTS.md (relative to CWD) Root-level project file (alternative location)

Resolution behavior: The @mention loader tries each path. If a file doesn't exist, it's skipped (no error). If multiple exist, all are loaded.

Why Use the foundation Bundle?

Because most bundles include foundation (either directly or indirectly), most sessions end up including common-agent-base.md and therefore the AGENTS.md references - unless you deliberately create a bundle that omits foundation's shared instructions.

How @mentions are Resolved (Technical Details)

The bundle system in amplifier-foundation handles @mention resolution:

Resolution Patterns

1. Namespaced mentions (@bundle-name:path)

@foundation:context/shared/common-agent-base.md
@lsp:agents/code-navigator.md

Resolved by looking up the bundle in the registry and finding the path within that bundle's context. See resolver.py#L52-L56

2. Relative path mentions (@path)

@AGENTS.md
@.amplifier/AGENTS.md

Resolved relative to current working directory. The resolver tries the path as-is, then with .md extension. See resolver.py#L58-L69

3. Home shortcut mentions (@~/path)

@~/.amplifier/AGENTS.md

The @~/ prefix is expanded to the user's home directory. This is handled by apps (like the CLI) that extend BaseMentionResolver with additional shortcuts.

Loading Process

When @mentions are encountered:

  1. Resolver.resolve(mention) - Converts @mention to file path
  2. MentionLoader.load_file(path) - Reads file content
  3. Recursive expansion - If loaded file contains @mentions, they're resolved too
  4. Content assembly - All content assembled into system message

Key code references: mentions/resolver.py , mentions/loader.py

flowchart TB B["foundation bundle.md"] -->|includes| S["@foundation:context/shared/common-system-base.md"] S -->|includes| A["@foundation:context/shared/common-agent-base.md"] A -->|contains| M1["@~/.amplifier/AGENTS.md"] A -->|contains| M2["@.amplifier/AGENTS.md"] A -->|contains| M3["@AGENTS.md"] M1 --> R["MentionResolver"] M2 --> R M3 --> R R --> L["MentionLoader loads files"] L --> SM["System message assembly"]

Resolution Details: Which Files Load?

The resolver tries each @mention in sequence:

All found files are loaded
Unlike traditional config where only one file wins, the @mention system loads ALL files that exist. If you have both ~/.amplifier/AGENTS.md AND .amplifier/AGENTS.md, both are included.

Resolution order (from common-agent-base.md line 112-114):

  1. @~/.amplifier/AGENTS.md - Global file (if exists)
  2. @.amplifier/AGENTS.md - Project file (if exists)
  3. @AGENTS.md - Root file (if exists)

No error if missing: If none of these files exist, execution continues normally. AGENTS.md is optional.

What AGENTS.md is For

From common-agent-base.md lines 212+:

The AGENTS.md file is the anchor point that appears at every turn of every AI conversation.

The file provides persistent instructions that:

See lines 128-131 of common-agent-base.md for the agent's instructions about when/how to modify AGENTS.md files.

Using AGENTS.md in Your Own Bundle

If you create a custom bundle, you can include AGENTS.md support: 

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

includes:
  - bundle: foundation  # Gets common-agent-base.md → AGENTS.md references
---

# My custom instructions

@foundation:context/shared/common-system-base.md

Or reference AGENTS.md directly in your bundle without foundation: 

---
bundle:
  name: my-minimal-bundle
---

# Instructions

Project guidance:
@.amplifier/AGENTS.md

Global guidance:
@~/.amplifier/AGENTS.md

For Application Developers

If you're building an app (not just using bundles), you can add custom @mention shortcuts by extending BaseMentionResolver. The CLI adds shortcuts like:

This is app-level functionality, not bundle-level. See the CLI's implementation for examples.