The Context Problem

After this chapter you can explain why the files that configure an AI coding agent behave like a project dependency, describe the drift that appears when they go unmanaged, and name the four properties a package-manager frame protects — Portability, Reproducibility, Provenance / security, and Governance — and how APM's three promises deliver them.

Agent context is a dependency you never declared

Before npm, pip, and Cargo, application dependencies lived wherever each developer happened to put them: a lib/ folder copied between machines, a zip emailed around, a README that listed “install these seven things first.” It mostly worked — until it didn't. Versions drifted, “works on my machine” became a punchline, and nobody could say with confidence what was actually running or where it came from. Package managers fixed this by turning scattered, hand-copied files into a declared dependency: one manifest that names what you need, one lockfile that pins exactly what you got, and one command that restores it anywhere.

The files that configure an AI coding agent are in that same pre-package-manager state today. Your agent context — the instructions and coding standards, the reusable prompts, the skills and agent personas, the plugins, and the Model Context Protocol (MCP) server configurations — quietly shapes the code an agent writes, how it reviews changes, and which external tools it can reach. That makes it a real project dependency. Yet most teams still hand-maintain it as loose files scattered across per-harness directories and personal home folders, with no single declared source of truth. APM's own framing is blunt: agents “need context to be useful … but today every developer sets this up manually. Nothing is portable nor reproducible. There's no manifest for it” (microsoft/apm README).

The drift problem

Undeclared, per-machine context drifts. Two developers believe they share a setup, but their instructions, prompts, or MCP servers have quietly diverged — the classic “works on my machine” failure, now aimed at AI agents. A shared README doesn't save you: documentation describes intent but never restores state, so drift returns the moment someone edits a local file. That is the difference APM draws between “follow this 12-step README” and a single install command (the three promises).

The four properties a package-manager frame protects

Reframing agent context as a dependency exposes four properties that go missing when it drifts. This book uses them as a lens in every chapter, so keep them handy:

• Portability — the same declared intent can travel between machines, in the forms your chosen harnesses support. Absent it, every developer's agent behaves a little differently and onboarding is manual.
• Reproducibility — a later restore returns to recorded dependency versions and content instead of silently resolving new ones. Absent it, a moving branch or an upstream edit silently changes what a “review prompt” actually contains.
• Provenance / security — you can tell where each piece of context came from, and content destined for the harness is checked before deployment. A prompt is, in effect, a program for an LLM, so an unvetted prompt or transitive MCP server is real supply-chain surface (security model, APM 0.31.0).
• Governance — an organization can decide which sources, scopes, and primitives are allowed, and have that decision enforced at install time. Absent it, policy lives in people's heads and is applied inconsistently.

Two distinctions are worth holding onto, because the rest of the book leans on them. Portability is about where declared intent can land; reproducibility is about returning to the recorded versions and content, not making different harness formats byte-identical. Security asks “where did this come from, and what risks can we detect?” while governance asks “is this allowed here?” The next section maps all four onto what APM actually ships.

Three files and one habit

APM borrows the manifest-plus-lockfile shape from npm, pip, and Cargo and applies it to the files that configure AI coding agents (What is APM?). Conceptually it is three files and one habit — you don't need any syntax yet, just the map:

• apm.yml — the manifest. The single human-authored source of truth: it names the context packages and MCP servers your project depends on, and which harnesses to target. This is what carries Portability.
• apm.lock.yaml — the lockfile. Machine-generated, never hand-edited: it records resolved sources and content hashes for repeatable restores and integrity checks (lockfile specification, APM 0.31.0). This carries Reproducibility and supports provenance; Chapter 6 explains the boundaries.
• apm-policy.yml — install-time governance (early preview). An organization's allow/deny rules for sources and MCP servers, checked at install time. The file isn't generated in each repo by default: APM discovers organization policy from the project's Git remote using host-specific locations. GitHub prefers .github-private before .github and other fallbacks; GitLab and Azure DevOps use different layouts. Authoring and enforcement boundaries come in Chapter 9. This carries Governance.
• apm install — the habit. The one command that reads the manifest (and lockfile) and materializes supported context for the selected targets. Onboarding stops being a 12-step README and becomes git clone then apm install (the three promises).

You author the manifest; APM records resolved state in the lockfile; the organization normally shares policy from a separate repository. Chapter 1 only names these files — layout and exact syntax arrive from Chapter 4 onward.

Four properties, three promises

The four properties are this book's teaching frame. APM itself commits to three promises, described in the docs as “deliberately small and load-bearing”: portable by manifest, secure by default, governed by policy. Here is the bridge, so no property is left an orphan slogan:

The book deliberately splits reproducibility out as its own property even though APM files it under the first promise. That is a teaching choice, not a fourth promise in the docs — a distinction the pitfalls below make sharper.

One context, many harnesses

A harness is a specific AI coding tool that reads agent-context files. Harness parity means preserving declared intent in the native forms each selected target supports, not identical bytes or every primitive on every harness. For example, APM projects a shared instruction into .github/instructions/, .claude/rules/, and .cursor/rules/, adapting its metadata for each tool (target matrix, APM 0.31.0). Targets come from your declaration or APM's resolution process, not a fan-out to every tool by default (Chapter 5). Meridian can maintain one authored instruction rather than three independent copies.

Package format matters too. Legacy plugins can project individual primitives, whereas recognized Agent Plugins v1 stay whole for native Copilot registration. They are not automatically flattened into equivalent Claude or Cursor files. Chapter 3 explains the primitive/package distinction.

Crucially, APM writes the files each tool already understands and then “stays out of the way at agent runtime” (What is APM?). It manages context; it does not proxy or sandbox the agent.

When a package-manager frame helps

APM earns its keep when context is shared and plural:

• Multiple developers depend on the same instructions, prompts, or skills — and drift between them costs real time.
• Multiple harnesses are in play (Meridian's Copilot + Claude Code + Cursor), so hand-maintaining per-tool files guarantees divergence.
• Onboarding should be reproducible, not a scavenger hunt across home directories.
• Security or compliance needs to inventory what agent tooling is installed and where it came from.
• An organization wants to enforce which sources and MCP servers are allowed.

When it's overkill

Be honest about the cases where a manifest is ceremony you don't need:

• A solo developer on a single harness with a couple of stable instruction files — the drift surface is tiny.
• Throwaway or spike work you won't share or restore.
• Context that is genuinely a personal preference (your own favorite prompts), not a project dependency the team relies on.

The dividing line is the one package managers drew decades ago: the moment context is shared, restored, or audited, “keep copies in sync by hand” stops scaling.

Meridian: from scattered files to one declaration

Here is Meridian's drift as an inventory. Nothing below is an APM file yet — it's four hand-edited files, plus an uninventoried set of MCP servers, none aware of the others:

As a file tree, the anti-pattern is stark — related intent, scattered and unpinned:

# Anti-pattern only -- four unmanaged sources of truth
.github/copilot-instructions.md       # backend rules, hand-edited
.claude/CLAUDE.md                     # older rules copied from another repo
.cursor/rules/frontend.mdc            # frontend-only conventions
~/prompts/review.prompt.md            # private, unversioned review prompt

The fix is not “write a better README.” It's to declare the context in one file the repo owns, then restore supported context for the selected harnesses. Here is the shape Meridian is heading toward — a minimal manifest that names the project and its harness targets, with dependency buckets ready to fill in later chapters:

name: meridian-checkout-agent-context
version: 0.1.0
description: Shared AI-agent context for the Meridian checkout service.
targets:
  - copilot
  - claude
  - cursor
dependencies:
  apm: []
  mcp: []
includes: auto

Read it as a promise, not yet a program. name, version, and description identify the package; targets lists the three harnesses Meridian uses; dependencies uses two buckets here — apm for context packages and mcp for MCP servers — both empty for now. includes: auto explicitly consents to deploying discovered local content; it is not an install-discovery filter (manifest reference, APM 0.31.0). One reviewable file, three harnesses, one future apm install. Chapter 4 develops this sketch; Chapter 5 runs the install for real.

Recap

• Agent context — instructions, prompts, skills, agents, plugins, MCP configs — is a real project dependency. Unmanaged, it drifts: “works on my machine,” for AI agents.
• A package-manager frame protects four properties: Portability, Reproducibility, Provenance / security, and Governance.
• APM delivers them through three official promises — portable by manifest, secure by default, governed by policy — so the four-property lens maps cleanly onto what APM ships.
• The map is three files and one habit: apm.yml (declare), apm.lock.yaml (reproduce), apm-policy.yml (govern), and apm install (restore).
• Harness parity means one declared intent in supported target-native forms, not identical files or universal plugin support. APM does not govern the agent runtime.
• Meridian's next step: turn four scattered per-harness files into one declared manifest.

Next

Package managers already solved most of this for application code. Chapter 2 — Lessons from Package Managers distills what npm, pip, and Cargo taught us — manifests, lockfiles, pinning, and the name-collision problem flagged above — and shows which lessons APM inherits.