holocron/plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md at 591b9cccb83f35f795fd15a748d7c99718bf9160

Files

Defame1297 1d07d1a76b docs(kyberforge): add Microsoft APM research reference set

Capture Microsoft's Agent Package Manager (APM) — overview, install,
config, CLI reference, registries/marketplace, monorepo shapes,
testing/validation, troubleshooting, and examples — as structured
reference docs under plugins/kyberforge/docs/research/docs/microsoft-apm/.

Lays the groundwork for issue #88 (build agents/skills to execute a
marketplace-to-APM conversion of this repo).

2026-08-10 17:06:07 +00:00

3.1 KiB

Raw Blame History

topic, source_keys

topic

source_keys

monorepo-and-repo-shapes

context7-microsoft-apm

Repo shapes

APM documents named patterns for how a repo can host multiple packages. Two are directly relevant to converting an existing multi-plugin repo:

Monorepo

Multiple independent plugins under one repo, each with its own manifest and .apm/ tree, plus a root apm.yml that lists them as local-path packages:

my-monorepo/
  apm.yml                          # marketplace + local-path packages
  packages/
    plugin-a/
      apm.yml                      # plugin-a's manifest
      .apm/
        agents/
          expert.agent.md
        instructions/
          style.instructions.md
        skills/
          my-skill/
            SKILL.md
    plugin-b/
      apm.yml
      .apm/
        prompts/
          review.prompt.md
        hooks/
          pre-tool.json

Monorepo-hybrid

The variant for a repo that both ships its own plugins and curates/re-lists others: multiple plugins live under a packages directory, each with its own manifest for independent compilation and testing, while a single root marketplace lists them all as local-path entries. This is the closest documented match to this repo's current plugins/<name>/ layout (each plugin already self-contained with its own skills/agents/hooks).

Scaffolding a monorepo

apm plugin init plugin-a --yes              # run from inside packages/plugin-a
apm plugin init plugin-b --yes              # run from inside packages/plugin-b
cd ../..
apm marketplace init --owner acme-org --name acme-monorepo
apm marketplace package add ./packages/plugin-a --name plugin-a
apm marketplace package add ./packages/plugin-b --name plugin-b

apm plugin init scaffolds a single package's apm.yml + .apm/ skeleton; apm marketplace package add registers an already-existing local package path into the root marketplace listing without re-scaffolding it — this is the command to point at each of this repo's existing plugins/* directories once each has its own apm.yml.

Per-package versioning

Plugins in a monorepo don't have to share a version with the root or each other:

marketplace:
  versioning: { strategy: per_package }
  packages:
    - { name: plugin-a, source: ./packages/plugin-a, version: 2.0.0 }
    - { name: plugin-b, source: ./packages/plugin-b, version: 0.1.0 }

Without this, the default versioning strategy ties all listed packages to the marketplace/root version — worth checking explicitly, since this repo's plugins (git, gitea, kyberforge, lint, core, bin) currently version independently (see the patch-bump-per-plugin pattern already in this repo's commit history).

What's still a manual translation, not an APM feature

Nothing in the docs describes an automated converter from an existing .claude-plugin/marketplace.json + plugin.json pair into apm.yml. The shapes are compatible (apm pack emits .claude-plugin/marketplace.json as a compile target), but populating each plugin's apm.yml metadata, type:, targets:, and dependencies: from the current manifests is manual per-package work, not a single migration command.

3.1 KiB Raw Blame History