Becoming a Producer

After this chapter you can take agent context that already works in one repo — a prompt, an instruction set, a skill — and extract it into a standalone, versioned APM package that other teams install through the same Chapter 5 apm install loop, instead of copying the files by hand. You will see why copy-paste reuse quietly recreates Chapter 1's drift, author a producer apm.yml, snapshot the package with apm pack, and read the crucial producer/consumer symmetry: producing adds no fifth property — it makes you the source of Portability, Reproducibility, Provenance, and Governance for everyone downstream.

Edition 1.2 — inspected CLI: exactly APM 0.31.0. The current worked example uses a separate local-bundle fixture; it does not silently change the original Meridian manifest. Clearly labelled v0.23.1 snapshots preserve the earlier package and private-Git story, not a claim that their historical outputs were produced by this release.

Reuse-by-copy is the Chapter 1 problem wearing a helpful face

Chapter 1 opened on drift: three copies of a review prompt in three home directories, each checking a slightly different threat model. Chapters 4–9 fixed that inside one repo — a manifest, a lockfile, a policy gate. But the moment a second team wants your good prompt, the old failure is one paste away. Copy the checkout-review prompt into another repo and the two copies begin to diverge immediately: no shared version, no lockfile, no review trail, no way to answer “which prompt produced this behaviour?” The uncomfortable truth this chapter names is that reuse-by-copy recreates the exact drift the book set out to kill.

Producing is the fix. It is the act of extracting context that already works — a prompt, a skill, an instruction set — into a standalone, versioned APM package that other repos install through the normal apm install loop, rather than copying files by hand. A copy is a point-in-time snapshot that starts drifting the instant it is made; a dependency is a pinned, hashed reference that a lockfile can reproduce and apm update can advance deliberately (Chapter 7). Producing converts copies into dependencies. APM frames the whole ramp around one promise: “there is no separate ‘build pipeline’ — the CLI is the build pipeline” (Producer overview).

Meridian can keep apm.yml + .apm/

Here is the part that removes the intimidation: Meridian needs no separate packaging language. Its producer package is a directory with apm.yml, a .apm/ source tree, and a README for consumers. That remains a good authoring layout, but it is not the only installable shape: root skills, skill collections, and plugins have their own intake rules (APM 0.31.0 package types).

You already know this shape from both sides. In Chapter 3 and Chapter 4 you authored primitives under .apm/instructions/ and .apm/prompts/; in Chapter 5 you consumed other people's packages that had exactly those directories. Producing is not new authoring — it is relocation into a package shape. The same source-vs-build split from Chapter 3 is now your responsibility: .apm/ is what you author; APM-managed files under .github/, .claude/, .cursor/, and shared .agents/ are deployment output. The generated lockfile is still a reviewable record to commit when sharing a reproducible project (Chapter 6). “Edit the source under .apm/ and re-run apm install — never edit the deployed copy” (package anatomy).

The symmetry: everything you consumed, you now become the source of

Producing does not add a fifth property to the book's four. It flips your role. Every benefit the earlier chapters named as a consumer win, the reader now supplies to downstream teams. When Meridian ships meridian-standards, its consumers get:

• Portability — one manifest compiles the same supported intent onto Copilot, Claude Code, and Cursor, not necessarily identical native bytes (Chapter 5);
• Reproducibility — declared Git dependencies get a resolved_commit and content_hash, so unchanged intent and its lock can be replayed; a packed bundle also records a per-payload-file SHA-256 map (Chapter 6);
• Provenance — a pinned, hashed, reviewable source that passes the same install-time scanners from Chapter 8;
• Governance — the package installs through the same apm-policy.yml gate from Chapter 9; a policy can even require it, as Meridian plans to do with require: meridian-finance/meridian-standards once the package is available.

This is the spine sentence of the whole book landing: the reader stops being an npm user and becomes an npm publisher — the same manifest, lockfile, and policy discipline, now pointed outward. APM states the symmetry directly: “every package you publish here installs through the [consumer ramp's] apm install command” (Producer overview). The official ramp is a five-rung ladder — author → compile → preview → pack → publish — and this chapter walks the two rungs that matter for internal reuse: author the package, and pack it, then closes the loop by installing the result back into a scratch repo. “You don't need a marketplace to start” (Producer overview).

Choose a contract that preserves what you are sharing

A package name, a distribution format, and a harness are different things. Putting a prompt in a ZIP does not make it a skill; adding a schema URL does not make every harness able to load it. Portability is bounded by the components the format carries and the consumer supports. The format choice below implements that boundary. Meridian must keep its engineering instructions, checkout-review prompt, and review skill together; a skill-only format is not an upgrade for that package.

For current commands, $Apm means the absolute path to the checksum-checked 0.31.0 executable from Chapter 5's setup, not whichever apm is on PATH. Use short, disposable copies outside the book checkout, with isolated user/config/cache directories. Fixture names below are relative to backend/examples/updates/1.2/producer/; copy the whole fixture, including hidden source directories and its genuine lockfile. No example needs a live agent session.

A producer package is a directory you already know how to read

Here is meridian-standards as a plain directory. Nothing is scaffolded by a special tool: an apm.yml, a README.md, and one subdirectory per primitive type under .apm/. Read it and you will recognise every file from earlier chapters.

meridian-standards/
├── apm.yml                                      # producer manifest (identity + distribution metadata)
├── README.md                                    # what the package is and how to install it
└── .apm/                                        # the SOURCE tree — one directory per primitive type
    ├── instructions/
    │   └── meridian-engineering.instructions.md # shared engineering rules (Money type, idempotency…)
    ├── prompts/
    │   └── checkout-review.prompt.md            # the checkout-review prompt, now reusable
    └── skills/
        └── secure-payment-review/
            └── SKILL.md                          # PCI / payment-review skill

Keep Meridian's primitives under .apm/<type>/; do not mix in extra root directories expecting APM to union every possible layout. Source authority determines which files count. In this APM layout, commands are authored as prompts: .apm/prompts/*.prompt.md, not a new .apm/commands/ directory (author primitives).

The producer manifest: identity + distribution intent

A consumer manifest answers “what does my repo need?” A producer manifest also answers “who is this package, where does it come from, and what is it for?” so other people can evaluate and discover it. It is the same apm.yml schema you wrote in Chapter 4 — producers simply fill in the optional distribution fields a private consumer manifest can leave out. Keep the original Meridian manifest visible: its omitted dependency mapping explains its output mode.

name: meridian-standards          # REQUIRED — package identity (its slug when others depend on it)
version: 1.0.0                    # REQUIRED — semver
description: Shared Meridian engineering instructions, prompts, and review skills.
author: Meridian Platform Engineering   # string -> { name: "…" } in the generated plugin.json
license: MIT                      # SPDX id — recorded in the lockfile & SBOM (omitting it -> NOASSERTION)
repository: https://github.com/meridian-finance/meridian-standards
keywords: [meridian, checkout, fintech, ai-agents]
type: hybrid                      # REAL enum, but RESERVED/INERT at v0.23.1 — changes no behaviour today
targets:                          # incl. copilot/claude -> routes `apm pack` to plugin.json mode
  - copilot
  - claude
  - cursor
includes: auto                    # consent to publish everything under .apm/ (the `apm init` default)

In 0.31.0, name and version remain the required identity fields. description, author, license, repository, and keywords are optional distribution metadata. A string author becomes a { "name": … } object in generated plugin metadata; repository and keywords also survive synthesis. These fields help consumers review ownership and reuse terms; a repository URL is not publisher authentication, and the producer's MIT license does not license every dependency. targets names the supported destinations; it is not decorative metadata (0.31.0 manifest reference).

The metadata is not decorative: it becomes the package's identity card on the other end. When you do not author a plugin.json yourself, apm pack synthesises one from apm.yml — so apm.yml stays the single source of truth (pack a bundle):

{
  "name": "meridian-standards",
  "version": "1.0.0",
  "description": "Shared Meridian engineering instructions, prompts, and review skills.",
  "author": { "name": "Meridian Platform Engineering" },
  "license": "MIT",
  "repository": "https://github.com/meridian-finance/meridian-standards",
  "keywords": ["meridian", "checkout", "fintech", "ai-agents"]
}

apm pack — declaration decides the output

Packing turns reviewed context into a handoff artifact. First ask which output your manifest requests, then inspect its contents. In 0.31.0 these output branches can coexist; a successful command is not, by itself, proof that an archive was created (pack routing).

The original Meridian manifest still has targets but no dependencies mapping, so it writes only in-tree plugin manifests. Omission and dependencies: null do not trigger bundling. The dry-run below previews that manifest-only route without changing project files:

# In a disposable copy of backend/examples/ch10/meridian-standards:
& $Apm install
& $Apm pack --dry-run --verbose
& $Apm pack --archive -o dist --verbose
# Outputs: .github/plugin/plugin.json and .claude-plugin/plugin.json.
# No archive in dist; Cursor does not get an ecosystem plugin.json.

Publication authority: local source versus attested dependencies

Chapter 4's declaration principle applies at publication, too: a directory's existence does not automatically authorize shipping it. For local plugin packing, .apm/ selects Meridian's source layout; an explicit includes list is exhaustive. This is not the same operation as install discovery (pack source selection).

Intake also respects declarations: an eligible APM manifest, backed by .apm/ or APM/MCP dependencies, takes precedence over a co-located plugin marker. Metadata-only apm.yml does not automatically override a plugin; root skills and collections remain distinct supported layouts. For a plugin, "skills": ["./skills/review"] declares the complete skill set, "skills": [] means none, and omission permits conventional discovery. Extra undeclared directories cannot expand an explicit list (package and component authority).

Your own source and someone else's dependency have different authority. A local prompt edited after install was packed with its new source content, not the older deployed copy. Dependency input, by contrast, is limited to the lock's deployed_files. For files selected for export, a missing file or a mismatch against recorded deployed_file_hashes fails packing; extra or edited cache content cannot become the publishing source. Older locks may lack recorded hashes; compatibility with those locks is not retroactive attestation of every file (dependency attestation). Install and audit before packing as a validation habit, not because every local file is read from the last deployment.

Author-only tooling belongs in devDependencies. It can be installed for the producer without becoming part of the consumer's bundle:

# Installed author tooling is not part of the published dependency closure.
name: dev-boundary
version: 1.0.0
description: A producer's development tooling must not ship.
license: MIT
targets: [copilot]
dependencies: {}
devDependencies:
  apm:
    - path: ./tool
includes: auto

# In the disposable dev-only fixture:
& $Apm install
& $Apm pack

Scaffold deliberately; do not confuse the two plugin families

The distribution contract is a choice, not a filename heuristic. apm plugin init without a format flag still creates apm.yml plus a Claude-compatible root plugin.json. Strict Agent Plugins 1.0 is opt-in and also creates mcp.json, with pinned schema URLs. Both scaffolds start at version 0.1.0, include empty runtime/dev dependency sections, and create neither a skill nor a lockfile (plugin scaffolding).

# In one empty directory: the Claude-compatible default.
& $Apm plugin init --yes --target copilot

# In a DIFFERENT empty directory: strict Agent Plugins 1.0.
& $Apm plugin init --yes --target copilot --format agent-plugin

The skill-only portable-plugin fixture demonstrates strict output without changing Meridian. Its bundle has root plugin.json with $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, mcp.json even with no servers, skills/review/SKILL.md, and an embedded lock recording pack.format: agent-plugin. APM 0.31.0, Agent Plugins 1.0.0, and OpenAPM's draft specification are separate version domains, not equivalent claims of support (format contract).

# In a disposable copy of portable-plugin:
& $Apm lock
& $Apm pack --format agent-plugin --verbose
# Output: build/portable-review-1.0.0/

To test native registration, copy the unchanged generated build/portable-review-1.0.0/ directory to pkg/ in a separate consumer, then declare it. The imperative install <bundle> route rejects this native package; it needs a dependency row (native Copilot intake).

name: native-consumer
version: 1.0.0
targets: [copilot]
dependencies:
  apm:
    - path: ./pkg

# In the separate native consumer, with the generated bundle at ./pkg:
& $Apm install      # observed exit 0: whole-plugin Copilot registration
& $Apm audit --ci   # observed exit 1: native canonical-IR replay failure

Registration wrote APM's Copilot marketplace/settings, not a loose duplicate skill, and did not locate or launch Copilot. Audit reported Native Agent Plugin canonical IR is missing; a separate source control with a legitimate metadata-only manifest removed the additional consistency complaint, not that replay failure. This is a real 0.31.0 limitation, not a network skip and not evidence that registration is unsupported. Do not add unattested files, edit the packed lock, or disable drift to hide it. Actual loading requires Copilot CLI >=1.0.81 and is SKIPPED-needs-network here because no configured harness/runtime session was run.

Catalog generation and release checking are different operations

A marketplace is a curated discovery index, commonly hosted in Git, not the REST package server. Use it when teams need to find several approved packages; one shared package can simply use a Git ref. apm marketplace init scaffolds the index declaration; apm pack generates its catalog. Consumers register a reachable Git-hosted catalog through apm marketplace add (marketplace producer flow).

# Author an index declaration; do not resolve or publish its placeholder.
& $Apm marketplace init --name meridian-marketplace --owner meridian-finance

A release check answers a different question: does the reviewed catalog match what these declarations and available metadata would generate? The marketplace fixture makes that question network-independent by keeping its single plugin under plugins/review/. Its plugin manifest explicitly declares only skills/review.

# The package source is contained in this fixture.
name: book-marketplace
version: 1.0.0
description: A minimal reviewed package index.
targets: [copilot]
marketplace:
  owner:
    name: Book Fixtures
  outputs:
    claude:
      path: catalog/marketplace.json
  packages:
    - name: review
      source: ./plugins/review
      description: A minimal review skill.
      version: 1.0.0

# In the disposable marketplace fixture:
& $Apm pack --offline --strict-metadata
& $Apm pack --offline --check-clean

--check-clean is read-only for project files, including modification times. A changed catalog returned 4 and was not repaired. A missing effective output path also returned 4; an override such as --marketplace-path claude=alternate/marketplace.json changes what is compared, not permission to create it. Use catalog/marketplace.json for the output path: the tested parser rejected a leading ./ there as traversal (release gates and effective paths).

The registry client exists; a public hosted hub is a separate claim

APM 0.31.0 ships an experimental REST registry client and an implementable HTTP API v1, including version-list, archive-download, and publication operations. That is not evidence of a Microsoft-operated public searchable hub, nor is a Git transport proxy the same service. Real use needs a compatible backend and authorized access. Git remains the default distribution route (experimental registries; HTTP API v1).

The registries feature is disabled by default; both gated manifest parsing and publish preview fail until it is enabled. This local-only preview demonstrates the separate registry archive contract, without uploading:

# Only in the disposable registry-preview fixture and isolated APM home:
& $Apm experimental enable registries
& $Apm install
& $Apm publish --package book-fixtures/review --dry-run
& $Apm experimental disable registries

Here --dry-run means no upload, not no writes. It creates registry-boundary-1.0.0.zip locally, with root apm.yml and .apm/, not the plugin wrapper produced by apm pack. Do not interchange the two ZIP contracts (publish preview behavior). Actual registry consumption/publication is SKIPPED-needs-network: no authorized compatible server or live publication was supplied or permitted. No credentials belong in the package manifest.

How to hand a package off

Pick the channel by the consumer's needs, not by the word “publish.” For normal versioned internal reuse, a declared Git ref is the simplest default. A hand-carried artifact and a replayable dependency are different contracts.

The producer → consumer round-trip

The real test of a produced package is not that it packs — it is that it stands alone. Local primitives can lean on paths, tools, or context that only exist in the origin repo, so the producer's discipline is to install the package into a fresh, throwaway repo and check that the intended context deploys there. “Install your own package in a scratch repo before declaring it shipped” (Producer overview). This is the consumer ramp from Chapter 5, seen from the producer's chair.

The v0.23.1 example tested a local-path source install, not an archive. The current source control also succeeded with apm install ./pkg and retained the relative ./pkg dependency spelling: local adds do not invariably become absolute paths. A local source still has to travel with its consumer; it is not an immutable Git pin. The separate test below instead consumes a real generated ZIP.

1. Pack the separate local-only Meridian fixture

Copy local-bundle/ to a short disposable directory. It reuses all three Meridian source files, trims optional discovery metadata, and deliberately declares an empty dependency mapping. The original backend/examples/ch10/meridian-standards/ is unchanged.

# Local content can be a bundle: the empty mapping is deliberate.
# This is a new fixture, not a change to the historical Ch10 package.
name: meridian-standards
version: 1.0.0
description: Shared Meridian engineering instructions, prompts, and review skills.
author: Meridian Platform Engineering
license: MIT
type: hybrid
targets: [copilot, claude, cursor]
dependencies: {}
includes: auto

# In the disposable local-bundle producer:
& $Apm install
& $Apm audit --ci
& $Apm pack --dry-run --verbose
& $Apm pack --verbose
& $Apm pack --archive -o dist --verbose

The actual directory is build/meridian-standards-1.0.0/, and the actual ZIP is dist/meridian-standards-1.0.0.zip. Alongside generated plugin.json and the enriched embedded lock, both contain:

• instructions/meridian-engineering.instructions.md — the engineering rules;
• commands/checkout-review.md — the authored prompt in the bundle's command layout;
• skills/secure-payment-review/SKILL.md — the review skill.

Packing enriched the embedded copy of the lock with bundle metadata without changing the producer's root lock. The output is a Claude-compatible plugin bundle, not strict Agent Plugins 1.0 and not the flat registry archive.

2. Install that ZIP into a fresh three-target consumer

In another empty scratch directory, replace the placeholder with the absolute path to the ZIP you just created. Pass the targets on the install command as well as init: without that explicit install flag, the 0.31.0 ZIP probe deployed only to Copilot despite a three-target consumer manifest.

# In a DIFFERENT, empty consumer directory:
& $Apm init --yes --target copilot,claude,cursor
& $Apm install '<absolute path to meridian-standards-1.0.0.zip>' --target copilot,claude,cursor
& $Apm audit --ci

3. Use declared Git for the ordinary restore contract

For day-to-day sharing, return to Chapter 5's declared-source loop. The small pinned-bundle fixture selects one public skill at an immutable commit, avoiding the full sample package's floating transitive graph. Explicit git keeps it Git-sourced even if registry defaults are configured. Unlike the one-shot ZIP, this declaration tells the next clone where to obtain the dependency again.

# One public skill with immutable source identity; no floating transitive graph.
name: pinned-bundle
version: 1.0.0
description: Lock-attested dependency content for a distributable review bundle.
author: Book Fixtures
license: MIT
targets: [copilot]
dependencies:
  apm:
    - git: microsoft/apm-sample-package
      ref: fb2851683be0e0e7711421d518bd8dba23b0b1f6
      path: .apm/skills/style-checker
includes: auto

# In a disposable copy of pinned-bundle; cold acquisition needs network:
& $Apm install
& $Apm install --frozen
& $Apm audit --ci
& $Apm pack --archive --json

The genuine lock records the full commit and the virtual skill's version: unknown; do not invent a semantic version for that subpath. Its deployed skill bytes are the attested dependency input to pack. Frozen replay here checks unchanged declared Git state, not deployed-content integrity; that is why audit is separate (Chapter 6).

Inspect build/pinned-bundle-1.0.0.zip on disk. This release's successful JSON report left bundle: null even while creating that archive; the JSON envelope is not a complete artifact inventory and null is not proof of absence (0.31.0 pack reporting).

Meridian's payoff: the extracted conventions come back as a dependency

In the story, Meridian publishes the source to its private Git host, tags v1.0.0, and makes meridian-checkout depend on it. The historical manifest below preserves that graduation to 1.0.0. Private distribution remains SKIPPED-needs-network: no real authorized Meridian repository or publication was supplied. The public declared-Git example above proves the current mechanism, not the fictional host.

# SKIPPED-needs-network: meridian-finance/meridian-standards is a private repo
name: meridian-checkout-agent-context
version: 1.0.0                    # <- the beat: the checkout context graduates from v0.x to 1.0.0
author: Meridian Checkout Team
targets: [copilot, claude, cursor]
dependencies:
  apm:
    - meridian-finance/meridian-standards#v1.0.0   # the extracted conventions, back in as a governed dep
  mcp: []
includes: auto

Carry the earlier consumer decisions forward: merge this dependency into the existing reviewed declarations, including Chapter 8's local-fetch MCP declaration, the other packages, and the review script. The reduced snapshot's mcp: [] and omitted script do not direct you to erase them. Retiring any existing dependency or capability requires its own reviewed change.

That dependency is the payoff of the whole book. The checkout team no longer copies its own conventions between services — it depends on them. Once the private source is available, the normal Git loop records its commit and content hash (Chapter 6), scans deployable content (Chapter 8), and gives Chapter 9's policy a named package to require. The same approved version can then supply each service's supported native context. The four properties the reader consumed for nine chapters are now the four properties they produce.

Recap

• Reuse-by-copy recreates Chapter 1's drift. Producing turns a working convention into one versioned, reviewable package that consumers restore identically — a dependency, not a fork.
• Meridian keeps its familiar source layout: apm.yml plus .apm/, not the only supported package shape. Producing is relocation, not new authoring; type: hybrid remains reserved metadata, not a layout or format switch.
• Pack routes by declaration. The unchanged historical manifest still writes in-tree plugin manifests. The separate dependencies: {} fixture produces a real default Claude-compatible directory and ZIP containing all three Meridian primitives.
• Publication authority is explicit. Local packing follows selected source and exhaustive includes; install does not use includes as a discovery allowlist. Dependencies supply attested deployed content, not arbitrary cached files. Dev tooling stays out of the bundle.
• Formats and support are bounded. Strict Agent Plugins 1.0 carries skills/MCP, not Meridian's complete package. Native registration works, but its known canonical-IR audit failure is separate from runtime loading. Bundle hashes detect changed payload relative to trusted metadata; they are not signatures.
• Catalog checks are read-only, not bundle certification. Drift or uncertifiable clean checks return 4; incomplete strict metadata returns 5, including when both gates are combined. A marketplace index, a Git proxy, and the shipped experimental REST registry client/API are different things; none proves a public hosted hub.
• Meridian extracted its checkout-review prompt, engineering instructions, and secure-payment skill into meridian-standards. The current example proves offline ZIP deployment with explicit copilot,claude,cursor targets; it is one-shot, unlike declared Git restore. The story closes with the conventions returning as a private dependency and meridian-checkout graduating to 1.0.0, without claiming a live publication.

Next

Meridian now produces a package its own teams consume — but a package that many teams must adopt raises new questions: how do you gate it in CI, serve it in an air-gapped environment, and govern its use across a whole organisation without turning developer setup into a bottleneck? Chapter 11 — Enterprise at Fleet Scale takes the producer and consumer ramps to org scale: apm audit --ci gating, Git proxying, air-gapped handoffs, and the adoption playbook that makes the Chapter 9 policy stick.