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 context can be materialized on any machine and any supported harness. Absent it, every developer's agent behaves a little differently and onboarding is manual.
• Reproducibility — a later restore reproduces the previously known-good context exactly, down to the bytes. 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 risky content is checked before it reaches disk. A prompt is, in effect, a program for an LLM, so an unvetted prompt or transitive MCP server is real supply-chain surface (the three promises).
• Governance — an organization can decide which sources, scopes, and primitives are allowed, and have that decision enforced automatically. 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 context can land (any machine, any harness); reproducibility is about whether it lands as the same bytes. And security asks “is this safe?” 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 primitives (skills, prompts, instructions, agents, plugins) 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 pins every resolved dependency to an exact source ref and a content hash, so two developers who install against the same lockfile get byte-identical context. This carries Reproducibility and half of provenance.
• apm-policy.yml — install-time governance. An organization's allow/deny rules, enforced when context is installed (including transitive MCP servers). Unlike the two files above, it isn't a per-repo default: it's an org-level artifact APM discovers from your organization's git remote (a .github, .apm, or _apm location), authored once in Chapter 9 rather than kept in every developer's checkout. This carries Governance.
• apm install — the habit. The one command that reads the manifest (and lockfile) and restores the declared context. Onboarding stops being a 12-step README and becomes git clone then apm install (the three promises).

You author the manifest first; APM generates the lockfile on install, and organization policy lives outside the repo entirely. 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 is APM's guarantee that one declared context restores the same skills, prompts, instructions, MCP servers, and more across all of them: “any developer runs apm install and gets the same agent context across GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini, Windsurf, and Kiro” (APM docs). APM compiles one source into each tool's native location — .github/ for Copilot, .claude/ for Claude Code, .cursor/ for Cursor — so the same intent lands in the harnesses you declare or APM detects, not fanned out to every tool by default (target resolution is covered in Chapter 5). Meridian's three-harness mix stops being three maintenance burdens and becomes one.

Crucially, APM writes the files each tool already understands and then “stays out of the way at agent runtime” (What is APM?). It restores context; it does not run, 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 let a single command restore it everywhere. 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 splits into two typed buckets — apm for primitives and mcp for MCP servers — both empty for now; includes: auto tells APM to auto-discover locally authored primitives. One reviewable file, three harnesses, one future apm install. Chapter 4 turns this sketch into a validated manifest; 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 context restores across many harnesses; APM configures files and stays out of the 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.