# Bazel

Recommend AXM extensions from a Bazel module and target Bazel modules from an extension.

The [two-way linking](/docs/package-ecosystems/overview) model applies to Bazel
modules just as it does to other ecosystems. A module recommends through
package-author metadata it ships with the module, and an extension targets the
module through a Bazel [purl](https://github.com/package-url/purl-spec).

The Bazel registry (Bzlmod / Bazel Central Registry) does not provide a
first-class field for arbitrary package metadata. Following the pattern other
sidecar-based ecosystems use (see
[Go modules](/docs/package-ecosystems/go-modules) and
[SwiftPM](/docs/package-ecosystems/swiftpm)), AXM reads an
`agent-extensions.json` sidecar shipped at the module root. After Bazel fetches
the module, AXM reads the sidecar from the extracted external-repository
directory (`external/<repo>/agent-extensions.json`).

## Recommend extensions from a module

Add an `agent-extensions.json` file at the module root, alongside
`MODULE.bazel`, with an `agentExtensions` array. Each entry is an extension
reference (`@owner/<type>/<name>`):

```jsonc
// agent-extensions.json
{
  "$schema": "https://axm.sh/schemas/agent-extensions.schema.json",
  "agentExtensions": [{ "ref": "@acme/packs/widget-kit" }],
}
```

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
module genuinely pairs with a bounded major line of the extension.

## Target Bazel modules from an extension

On the extension manifest (`skill.json`, `pack.json`, `subagent.json`, …), add a
`packages` array with a Bazel [purl](https://github.com/package-url/purl-spec):

```jsonc
// pack.json
{
  "packages": [{ "purl": "pkg:bazel/rules_widget" }],
}
```

Use the module name as registered in the Bazel Central Registry as the purl
name.

### Version ranges

Default to identity-only. Add a [VERS](https://github.com/package-url/vers-spec)
`versionRange` with the `bazel` scheme only when the extension depends on module
APIs introduced or removed in a known range:

```jsonc
{
  "packages": [
    {
      "purl": "pkg:bazel/rules_widget",
      "versionRange": "vers:bazel/>=1.0.0|<2.0.0",
    },
  ],
}
```

## Official status

When the Bazel module recommends an extension through the AgentXM Registry
**and** that extension names the module as a companion via its purl, AXM derives
**official** status for the pair — no extra flag. See
[Official extensions](/docs/package-ecosystems/overview#official-extensions).

> The Bazel package-author metadata convention is still being finalized. The
> sidecar location above mirrors the documented sidecar ecosystems; the
> `pkg:bazel` purl is the stable identity an extension uses to target a module.
> Confirm the current shape against the
> [`polyglot-examples`](https://github.com/agentxm/polyglot-examples) fixtures
> before relying on it.