git-a2a

git-a2a

Connect a Git component together with the agent responsible for it.

git-a2a is a cross-platform component dependency manager. A component repository publishes code, one A2A Agent Card reference for its owner, and optionally a readable surface such as API documentation, examples, or source. A consumer connects the code through its own platform's adapter and records the exact commit, adapter, and package-manager variant.

git-a2a does not send messages, manage tasks, run agents, or host Agent Cards. Use the usable Agent Card reference shown by git a2a list with an external A2A client: an HTTPS URL or a local copy of a repository-relative card from the applied commit.

Quick start

Run the binary directly as git-a2a, or install it on PATH and use Git's equivalent git a2a form:

git a2a init
git a2a add https://github.com/acme/lib-utils.git --name lib-utils
git a2a list lib-utils
git a2a pull lib-utils
git a2a remove lib-utils

There are exactly five domain commands:

pull is adapter lifecycle, not a wrapper around git pull. All bindings of a polyglot component use the same resolved commit. Adapter and manager selection is durable: a later change to PATH or consumer marker files cannot silently switch it.

Component contract

a2amodule.yml uses schema 2:

schema: 2
component:
  id: lib-utils
  description: Shared parsing and validation utilities.
  repository: https://github.com/acme/lib-utils.git
  exports:
    - adapter: npm
      name: "@acme/lib-utils"
    - adapter: pypi
      name: acme-lib-utils
  surface: docs/public
agent:
  name: lib-utils-owner
  card: https://agents.acme.example/lib-utils/.well-known/agent-card.json

The Agent Card remains the authority for the agent's interfaces, skills, and authentication. The manifest deliberately does not duplicate them. init may create an incomplete local manifest without agent; a repository consumed by add or pull must declare agent.card.

The optional component.surface is published data from the same applied commit and is materialized under .git-a2a/surfaces/NAME. If no surface is declared, no repository content is implicitly published. Surface is not an installation mechanism and is not a submodule.

See the manifest reference, authoring guide, consumer guide, and schema 1 migration guide.

Adapter matrix

Every existing platform integration is retained. Native adapters apply dependencies through the platform's own manager, updating declarations, native locks, and installed or resolved state; build-system adapters compose with one submodule checkout rather than copying source into a second tree.

Git submodule is an ordinary adapter with the same add/pull/remove/inspect lifecycle. Native lockfiles remain owned by their package managers. See Works with for the detailed matrix and boundaries.

Installation

These existing installation channels are preserved. Commands track the latest stable release; pin a version in CI.

Linux .deb, .rpm, and .apk packages are attached to GitHub Releases. Release archives cover Darwin, Linux, and Windows on amd64/arm64 and include checksums and SBOMs. The standalone installers verify checksums and support version pinning, destination selection, and dry-run. Package-manager installs are updated with that package manager; the binary has no self-updater.

Maintainer and provenance details are in the release guide.

Documentation

• CLI reference
• Manifest reference
• Authoring a component
• Consuming components
• Agents and external A2A clients
• Supported adapters
• Migrating from schema 1
• FAQ
• Release and installation maintenance

The portable Agent Skill teaches a coding agent this five-command workflow. It does not configure an MCP server or agent harness.

Specification as source

Repository decisions and invariants live in .hint files beside the artifacts they govern. hint <path> returns the knowledge governing a path, and hint status checks for drift. See HINT for the tool and format.

License: MIT.