Composer

AXM reads PHP extension metadata from an agentExtensions field nested under extra in composer.json. This is the two-way linking model applied to the Composer ecosystem.

Add an extra.agentExtensions array to composer.json. Each entry is an extension reference (@owner/<type>/<name>):

// composer.json
{
  "name": "agentxm/example-tinyflags",
  "extra": {
    "agentExtensions": [{ "ref": "@examples/packs/php-composer-tinyflags" }],
  },
}

Composer leaves extra untouched, so the field travels with your published package and is available to consumers after composer install.

Keep recommendations identity-only — omit versionRange. AXM resolves the reference to the newest matching extension version and pins it in the user's axm.lock. Prefer recommending a single pack so you keep one stable reference while its contents evolve.

Add a semver versionRange only when your package genuinely pairs with a bounded major line of the extension:

{
  "extra": {
    "agentExtensions": [
      {
        "ref": "@examples/packs/php-composer-tinyflags",
        "versionRange": "^1.0.0",
      },
    ],
  },
}

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a Composer purl. Composer purls put the Packagist vendor in the namespace and the package name in the name, separated by /:

// pack.json
{
  "packages": [{ "purl": "pkg:composer/agentxm/example-tinyflags" }],
}

Default to identity-only. Add a VERS versionRange with the composer scheme only when the extension depends on package APIs introduced or removed in a known range:

{
  "packages": [
    {
      "purl": "pkg:composer/agentxm/example-tinyflags",
      "versionRange": "vers:composer/>=0.1.0|<1.0.0",
    },
  ],
}

When the Composer package recommends an extension through the AgentXM Registry and that extension names the package as a companion via its purl, AXM derives official status for the pair — no extra flag. See Official extensions.

The php-composer-lib and php-composer-app directories in polyglot-examples are the working fixtures for everything above. The package publishes a TinyFlags companion pack and recommends it from extra.agentExtensions in composer.json; the pack and each skill declare the package's Composer purl as an identity-only companion package.