README
¶
a2ahub
a2a is a single, stdlib-first CLI for exchanging structured
agent-to-agent contracts and artifacts through a plain GitHub repository (a
"space"): drafting them from templates, validating them, opening a PR,
tracking their lifecycle, and reading the resulting state back out — no
server, no database, just git.
Install
Shell installer (macOS/Linux, downloads and verifies the latest release):
curl -fsSL https://raw.githubusercontent.com/ydnikolaev/a2ahub/main/scripts/install.sh | sh
The script resolves the latest GitHub release, downloads the platform
binary + SHA256SUMS, verifies the SHA-256 before installing, and refuses
to install on a mismatch or a missing checksum entry. Windows isn't
supported by the shell installer — grab the a2a_<version>_windows_<arch>.zip
archive from the releases page
instead.
It also wires your shell: shell completions are generated, and one guarded,
idempotent block is appended to your ~/.zshrc / ~/.bashrc /
config.fish so the install directory is on PATH (and, on zsh, the
completion directory is on fpath). Open a new shell — or source that
file — to pick it up. Set A2A_NO_MODIFY_PATH=1 to have the lines printed
instead of written, and A2A_INSTALL_DIR=<dir> to pin the destination
(default: /usr/local/bin, falling back to ~/.local/bin).
go install (builds from source):
go install github.com/ydnikolaev/a2ahub/cmd/a2a@latest
Manual download: grab a2a_<version>_<os>_<arch>.tar.gz (or .zip on
Windows) from the releases page,
unpack, and put a2a on your PATH.
Quick usage
a2a init # set up project config (.a2a/config.yaml)
a2a connect <space-repo> # register + mirror-clone a space
a2a new <type> # draft an artifact from a template
a2a validate <path> # validate a draft (V1/V2)
a2a submit <artifact> # validate + open a PR for a draft
a2a sync # fetch all connected spaces
a2a inbox # computed inbox across connected spaces
a2a show <ref> # an artifact + folded state + events
a2a update # self-update to the latest release
Run a2a with no arguments to see the full command list, including the
lifecycle verbs (ack, accept, decline, respond, verify, ...) and
contract (contract publish/deprecate/retire/diff/verify-export).
Credentials
Read verbs work offline against the local mirror. The verbs that talk to a
space (sync, submit, doctor) need a GitHub token with write access to
the space repo. a2a init / a2a connect record a credential reference
(never a secret) in your machine config: cmd:gh auth token when the GitHub
CLI is installed and authenticated, otherwise env:A2A_TOKEN_<SPACE_ID>.
Exporting A2A_TOKEN_<SPACE_ID> always overrides whatever is configured —
for a space with id getvisa:
export A2A_TOKEN_GETVISA="$(gh auth token)"
Verifying a release
Every release publishes a SHA256SUMS file, a per-asset cosign bundle, and
SLSA build provenance. See SECURITY.md for the gh attestation verify and cosign verify-blob commands.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
a2a
command
Command a2a is the single a2ahub binary: CLI + (later) local MCP server + validator + statusline provider + local HTML generator (§7.1, D-005, R-004).
|
Command a2a is the single a2ahub binary: CLI + (later) local MCP server + validator + statusline provider + local HTML generator (§7.1, D-005, R-004). |
|
internal
|
|
|
artifact
Package artifact implements the artifact model shared by every a2ahub surface: the two §3.3 ID classes (standing, exchange/broadcast), ULID lifecycle-event IDs, structural frontmatter parse/serialize, and digests.
|
Package artifact implements the artifact model shared by every a2ahub surface: the two §3.3 ID classes (standing, exchange/broadcast), ULID lifecycle-event IDs, structural frontmatter parse/serialize, and digests. |
|
cache
Package cache implements the P7 read surface (spec docs/features/v1-min-2026-07/specs/07-read-surface-statusline.md): it composes internal/fold over the committed history of every connected space's local mirror clone (internal/space) into the inbox/outbox query sets §4.2/§7.2 defines, plus per-system read cursors, the pending-merge overlay, and mirror staleness/sync-age.
|
Package cache implements the P7 read surface (spec docs/features/v1-min-2026-07/specs/07-read-surface-statusline.md): it composes internal/fold over the committed history of every connected space's local mirror clone (internal/space) into the inbox/outbox query sets §4.2/§7.2 defines, plus per-system read cursors, the pending-merge overlay, and mirror staleness/sync-age. |
|
cli
Real internal/cache-backed PendingMarker/CacheRemover (plan 07 Placement decision, binding): internal/cli's own P6-defined seams (adapters.go) filled with the P7 primitives that back them.
|
Real internal/cache-backed PendingMarker/CacheRemover (plan 07 Placement decision, binding): internal/cli's own P6-defined seams (adapters.go) filled with the P7 primitives that back them. |
|
coveragepolicy
Package coveragepolicy is the SINGLE SOURCE OF TRUTH for a2ahub's test- coverage thresholds — one global floor plus per-package minimums — shared by two consumers: the coverage gate that runs under `go test` (policy_test.go) and the CI/local checker (covercheck.go, run by `make coverage`).
|
Package coveragepolicy is the SINGLE SOURCE OF TRUTH for a2ahub's test- coverage thresholds — one global floor plus per-package minimums — shared by two consumers: the coverage gate that runs under `go test` (policy_test.go) and the CI/local checker (covercheck.go, run by `make coverage`). |
|
e2e
Package e2e — coverage.go implements the P26 coverage manifest (spec 26 §1/§11): a table mapping every catalog CLI verb to real evidence — a verb-invoking txtar scenario OR a direct-construction Go test — or an explicit, justified skip.
|
Package e2e — coverage.go implements the P26 coverage manifest (spec 26 §1/§11): a table mapping every catalog CLI verb to real evidence — a verb-invoking txtar scenario OR a direct-construction Go test — or an explicit, justified skip. |
|
feedback
Package feedback is the P25 agent-feedback core: draft/validate/ledger/ triage/submit for the consumer-agent -> product-repo feedback channel (docs/features/v1-min-2026-07/specs/25-agent-feedback.md).
|
Package feedback is the P25 agent-feedback core: draft/validate/ledger/ triage/submit for the consumer-agent -> product-repo feedback channel (docs/features/v1-min-2026-07/specs/25-agent-feedback.md). |
|
fold
Package fold implements the a2ahub lifecycle fold engine (spec docs/features/v1-min-2026-07/specs/04-fold-engine.md, plan docs/the-plan/plan/03-domain.md §3.4-3.5).
|
Package fold implements the a2ahub lifecycle fold engine (spec docs/features/v1-min-2026-07/specs/04-fold-engine.md, plan docs/the-plan/plan/03-domain.md §3.4-3.5). |
|
host
Package host implements the §T1 5-primitive host adapter interface plus its v1 GitHub implementation: push an ephemeral branch, open a PR with auto-merge always enabled, read the required-check and review-approval state, and locate an already-open/merged PR by its deterministic head branch (the idempotent-retry read path).
|
Package host implements the §T1 5-primitive host adapter interface plus its v1 GitHub implementation: push an ephemeral branch, open a PR with auto-merge always enabled, read the required-check and review-approval state, and locate an already-open/merged PR by its deterministic head branch (the idempotent-retry read path). |
|
html
Package html assembles the `a2a html` / `a2a dashboard` local view's data model (Data) from the shipped read surface (internal/cache Store + space manifests + consumes.yaml) and renders it into a self-contained static HTML page by injecting the model as JSON into an embedded, designed template.
|
Package html assembles the `a2a html` / `a2a dashboard` local view's data model (Data) from the shipped read surface (internal/cache Store + space manifests + consumes.yaml) and renders it into a self-contained static HTML page by injecting the model as JSON into an embedded, designed template. |
|
mcp
Package mcp implements P14 (`a2a mcp`, OP-216): a stdio JSON-RPC 2.0 MCP server whose tool registry maps 1:1 to the §7.7-enumerated OP subset.
|
Package mcp implements P14 (`a2a mcp`, OP-216): a stdio JSON-RPC 2.0 MCP server whose tool registry maps 1:1 to the §7.7-enumerated OP subset. |
|
notes
Package notes parses and range-queries the P31 release-notes corpus: an authored, version-keyed YAML file per shipped a2a version (releasenotes/*.yaml, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json), embedded by the releasenotes package.
|
Package notes parses and range-queries the P31 release-notes corpus: an authored, version-keyed YAML file per shipped a2a version (releasenotes/*.yaml, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json), embedded by the releasenotes package. |
|
release
Package release implements the P19 (OP-217) self-update primitives: fetching the latest product-repo release (Source), verifying a downloaded asset (Verifier — an unconditional ChecksumVerifier plus a T2-interim UNVERIFIED signature slot, checksum-only per the 2026-07-22 amendment), downloading the platform asset triplet (Download), the post-download version self-check (SelfCheckVersion), the atomic same-filesystem binary swap (Swap), version-floor resolution (Resolve), and the TTL'd machine-level "latest known release" cache (CheckState/ReadCheck/ WriteCheck/ReadLatest) plus its background checker (NewChecker).
|
Package release implements the P19 (OP-217) self-update primitives: fetching the latest product-repo release (Source), verifying a downloaded asset (Verifier — an unconditional ChecksumVerifier plus a T2-interim UNVERIFIED signature slot, checksum-only per the 2026-07-22 amendment), downloading the platform asset triplet (Download), the post-download version self-check (SelfCheckVersion), the atomic same-filesystem binary swap (Swap), version-floor resolution (Resolve), and the TTL'd machine-level "latest known release" cache (CheckState/ReadCheck/ WriteCheck/ReadLatest) plus its background checker (NewChecker). |
|
schema
Package schema loads and compiles the embedded product schema corpus (schemas.FS: envelope/v1 base + 8 type extensions, event/v1, manifest/v1, consumes/v1) with santhosh-tekuri/jsonschema/v6, and loads the error-code registry (schemas/errors/v1/registry.yaml).
|
Package schema loads and compiles the embedded product schema corpus (schemas.FS: envelope/v1 base + 8 type extensions, event/v1, manifest/v1, consumes/v1) with santhosh-tekuri/jsonschema/v6, and loads the error-code registry (schemas/errors/v1/registry.yaml). |
|
space
Package space implements the §4.2 space layout model, space.yaml manifest load, project/machine configuration (§7.4), credential resolution (§7.4/§10.5), mirror clones, and the D-002/D-026 write funnel.
|
Package space implements the §4.2 space layout model, space.yaml manifest load, project/machine configuration (§7.4), credential resolution (§7.4/§10.5), mirror clones, and the D-002/D-026 write funnel. |
|
surface
Package surface holds the provider-surface registry: the verified facts about where each AI coding agent looks for a skill (its "skills home") and where it reads always-on context (CLAUDE.md, AGENTS.md, …), plus the detection and link logic that use those facts.
|
Package surface holds the provider-surface registry: the verified facts about where each AI coding agent looks for a skill (its "skills home") and where it reads always-on context (CLAUDE.md, AGENTS.md, …), plus the detection and link logic that use those facts. |
|
template
Package template embeds and renders the P2 per-type canonical templates (schemas/templates/v1/*.md, §5.6) for `a2a new`/`a2a template list|show` (P6).
|
Package template embeds and renders the P2 per-type canonical templates (schemas/templates/v1/*.md, §5.6) for `a2a new`/`a2a template list|show` (P6). |
|
validate
Package validate is THE one validation engine (D-011): schema, referential, lifecycle, and policy classes, exposed through two invocation points — ValidateDraft (V1, authoring) and ValidateForSubmit (V2, pre-write).
|
Package validate is THE one validation engine (D-011): schema, referential, lifecycle, and policy classes, exposed through two invocation points — ValidateDraft (V1, authoring) and ValidateForSubmit (V2, pre-write). |
|
version
Package version is the SSOT bare-version comparator: dotted major.minor.patch parsing and strict-older comparison, stdlib-only, with no dependency on any other a2ahub package.
|
Package version is the SSOT bare-version comparator: dotted major.minor.patch parsing and strict-older comparison, stdlib-only, with no dependency on any other a2ahub package. |
|
Package releasenotes embeds the authored, version-keyed release-notes corpus (P31: one file per shipped a2a version, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json) so it ships inside the `a2a` binary and is surfaced by `a2a whatsnew` without a network call — the same "schema and payload travel as one artifact" rationale schemas/embed.go documents for the product schema corpus.
|
Package releasenotes embeds the authored, version-keyed release-notes corpus (P31: one file per shipped a2a version, schema release-notes/v1, schemas/release-notes/v1/release-notes.schema.json) so it ships inside the `a2a` binary and is surfaced by `a2a whatsnew` without a network call — the same "schema and payload travel as one artifact" rationale schemas/embed.go documents for the product schema corpus. |
|
Package schemas embeds the product schema corpus — envelope, event, manifest, consumes JSON schemas, the error-code registry, and the per-type templates — so it ships inside the `a2a` binary (§5.1, D-009: "schemas and validator travel as one artifact").
|
Package schemas embeds the product schema corpus — envelope, event, manifest, consumes JSON schemas, the error-code registry, and the per-type templates — so it ships inside the `a2a` binary (§5.1, D-009: "schemas and validator travel as one artifact"). |
|
Package skill embeds the a2ahub expert-skill tree so the `a2a` binary can install it into a consumer repo (`a2a skill install`).
|
Package skill embeds the a2ahub expert-skill tree so the `a2a` binary can install it into a consumer repo (`a2a skill install`). |
|
Package spacetemplate embeds the space-template/ tree so `a2a space init` (internal/cli's SpaceCommand, spec 33 §12) can scaffold a new space repo from it directly, without an operator hand-copy step.
|
Package spacetemplate embeds the space-template/ tree so `a2a space init` (internal/cli's SpaceCommand, spec 33 §12) can scaffold a new space repo from it directly, without an operator hand-copy step. |
|
testkit
|
|
|
fakegithub
Package fakegithub is an in-process stand-in for the GitHub REST/GraphQL surface internal/host talks to, backed by REAL local git repositories.
|
Package fakegithub is an in-process stand-in for the GitHub REST/GraphQL surface internal/host talks to, backed by REAL local git repositories. |
|
spacefixture
Package spacefixture builds throwaway git space fixtures for tests: a bare "origin" repo (the space's remote, simulating a git host with zero network) plus one working clone per simulated system, seeded with the §4.2 tree.
|
Package spacefixture builds throwaway git space fixtures for tests: a bare "origin" repo (the space's remote, simulating a git host with zero network) plus one working clone per simulated system, seeded with the §4.2 tree. |
Click to show internal directories.
Click to hide internal directories.