Your agent team found a better way to work. Let it travel.¶

Pick what should travel¶

Prepare in 60 seconds¶

Already have a signed artifact? In about a minute you can verify it and prepare a reviewable local registry diff. Want a remix first? Open the static Studio, import a workflow or Agent Graph, export the unsigned draft, then sign it locally. Studio never receives a private key or writes to the registry.

git clone https://github.com/lboel/acx.git && cd acx && npm test

The artifact preparation itself creates no network write:

# 1. Verify the signed bytes and clean package contract
node --experimental-sqlite src/cli.mjs verify my-agent.acx
node --experimental-sqlite src/cli.mjs spec my-agent.acx

# 2. Preview the exact registry destination — no files written
node --experimental-sqlite src/cli.mjs share agent my-agent.acx \
  --slug my-agent --dry-run

# 3. Prepare the artifact + generated discovery card locally
node --experimental-sqlite src/cli.mjs share agent my-agent.acx \
  --slug my-agent

# 1. Verify structure, safety profile, digest, signature, and publisher
node --experimental-sqlite src/cli.mjs workflow lint team.cal.json --publish
node --experimental-sqlite src/cli.mjs workflow verify team.cal.json

# 2. Preview, then prepare the canonical registry file
node --experimental-sqlite src/cli.mjs share workflow team.cal.json --dry-run
node --experimental-sqlite src/cli.mjs share workflow team.cal.json

# 1. Verify the information architecture and its signed identity
node --experimental-sqlite src/cli.mjs graph lint \
  team.agent-graph.json --publish
node --experimental-sqlite src/cli.mjs graph verify \
  team.agent-graph.json

# 2. Preview, then prepare the canonical registry file
node --experimental-sqlite src/cli.mjs share graph \
  team.agent-graph.json --dry-run
node --experimental-sqlite src/cli.mjs share graph \
  team.agent-graph.json

Finish every path with:

node --experimental-sqlite tools/build-registry-index.mjs
npm test
git diff --check
git diff -- registry/

Publish the prepared diff separately¶

Only after the local checks pass:

1. fork lboel/acx into an account you control;
2. create a focused branch from the current upstream main;
3. commit only the reviewed artifact, generated discovery metadata, and deterministic index;
4. push that branch to your fork; and
5. open a draft pull request back to lboel/acx.

You perform those steps yourself or explicitly authorize a GitHub-capable agent to perform them. The acx share command and the 60-second preparation path stop before every remote write.

Each reviewed and merged PR creates an immutable, shareable detail link in the static Exchange. The next person can inspect and verify it, preserve its signed lineage in a remix, and publish a new version — without an account or proprietary API.

What the pull request proves¶

The registry never executes a submitted agent, workflow, or graph. CI opens cartridges read-only, recomputes content-addressed digests, verifies Ed25519 DSSE/in-toto signatures, validates each publication profile, and regenerates registry/index.json. Human review checks the supplied namespace-proof evidence, licensing metadata, quality, and community fit; the PR path itself is not a namespace proof.

Share an agent¶

Use an .acx when the reusable unit is an agent that has learned a domain, carries skills, or has an independently proven level.

The canonical PR surface is:

registry/cartridges/<publisher>/<id>/<version>/
├── cartridge.acx   # signed authority
└── README.md       # generated discovery card
registry/index.json # deterministic index

<id> and SemVer <version> come from the cartridge's ROM-bound acx.artifact_id and acx.artifact_version; a requested --slug must equal that id. Display names never determine the coordinate.

Recipients can inspect without installing:

acx verify registry/cartridges/<publisher>/<id>/<version>/cartridge.acx
acx load registry/cartridges/<publisher>/<id>/<version>/cartridge.acx --print-only

Share a workflow or team¶

Use a .cal.json when the reusable unit is a repeatable outcome: a research council, release loop, incident team, review circuit, or any other bounded collaboration.

Workflows bind roles and capabilities, not local machine identities. A recipient first verifies the shared graph, then staffs its slots from their own cartridges:

acx workflow verify \
  registry/cals/io.github.lboel/research-council/1.0.0.cal.json
acx workflow ready \
  registry/cals/io.github.lboel/research-council/1.0.0.cal.json \
  --cartridges ./my-roster

Explore the signed Research Council for a non-coding team or the Ship a Feature walkthrough for an iterative engineering loop.

Published workflows use publisher + id + SemVer + digest as their immutable identity:

registry/cals/<publisher>/<id>/<version>.cal.json

If you change signed bytes, increment SemVer. Do not replace an existing coordinate. A remix may add a signed lineage.parents[] entry with the parent's publisher, id, version, digest, and relation.

Share an Agent Graph¶

Use an .agent-graph.json when the reusable insight is the team's information architecture rather than a task sequence:

• who stewards product intent, evidence, delivery status, decisions, or tacit context;
• who can direct, request, advise, report, review, approve, or escalate to whom;
• what knowledge each route carries and which declared route brings a response back;
• where several workflows or informal loops converge into one bounded synthesis.

A CAL says what happens next. An Agent Graph says who owns the context, who can direct whom, where reports return, and where separate loops meet.

The canonical PR surface is one readable signed file:

registry/graphs/<publisher>/<id>/<version>.agent-graph.json
registry/index.json

acx graph lint product-delivery.agent-graph.json --publish
acx graph sign product-delivery.agent-graph.json \
  --publisher io.github.yourhandle \
  --out product-delivery.signed.agent-graph.json
acx graph verify product-delivery.signed.agent-graph.json
acx graph digest product-delivery.signed.agent-graph.json
acx share graph product-delivery.signed.agent-graph.json --dry-run
acx share graph product-delivery.signed.agent-graph.json

The graph contains descriptions and references, never the actual roadmap, private messages, credentials, or knowledge payloads. authority describes a relationship; it never grants a tool permission. Reporting cycles are useful, while mandatory direction stays unambiguous and bounded.

See the animated Agent Graph guide to read the Product Owner ↔ Developer reporting loop and the research + delivery convergence pattern. The registry's Product Delivery graph is the signed, inspectable example.

Every published acx-workflow loop binding pins workflowRef.publisherId, id, version, and digest. The registry gate resolves that exact dependency; it never substitutes “latest.” Use acx graph digest when authoring or reviewing the pin.

Let an agent prepare its own share PR¶

The repository ships skills/acx-share-agent/, a standard Agent Skill usable by Codex and other SKILL.md-aware hosts. It teaches an agent to verify itself, a workflow, or an Agent Graph; prepare only safe registry paths; regenerate the index; run conformance checks; and draft the pull-request body. Fork, branch, commit, push, and draft-PR creation remain separate actions that require explicit authorization.

Install it for Codex:

cp -R skills/acx-share-agent "${CODEX_HOME:-$HOME/.codex}/skills/"

Then ask:

Use $acx-share-agent to verify and prepare this agent, workflow, or Agent Graph for sharing through the ACX registry.

The skill intentionally stops before remote writes unless the human explicitly authorizes a push or PR. It never auto-merges a registry submission.

Make the share travel further¶

When posting an ACX artifact, include four things:

1. Outcome: “A three-agent research council that returns a decision-ready brief.”
2. Proof: the ROM or workflow digest and verification result.
3. Fit: the required role, capabilities, tools, and context.
4. Fork point: the registry or workflow link plus one verification command.

That makes the artifact understandable before download and trustworthy after download.

The Exchange also displays signed lineage and the separate status ledger. A deprecated, withdrawn, or superseded marker warns recipients without rewriting history. It is advisory registry state, not a signature, key, or credential revocation.