15 APM Future Registry Service

Status

Accepted

Context

The APM ecosystem plan (phase 1) covers six distinct concerns:

1. APM registry — apm-registry (migrated from agent-primitives)
2. APM CLI — gh-calab (migrated from gh-agent-primitives)
3. Generated distribution — .github-private
4. Staff marketplace portal — calab-handbook (this repo)
5. Consumer repositories — workspaces that declare APM dependencies
6. Optional future registry service — only if metadata must aggregate many independently released source repos

Concern 6 was deferred in the plan table but required a formal decision record. ADR 011 in calab-ai/apm-registry (docs/decisions/011-future-registry-service-decision.md) contains the full analysis and evidence from the implementation branches.

This decision documents the handbook’s perspective on that decision and records the impact on the handbook architecture.

Decision

A separate APM registry service repo is not needed for Phase 1.

The handbook remains a consumer of static generated catalog artifacts (portal-data.json) published as GitHub release assets from apm-registry. No additional registry service, API gateway, or catalog backend is required to build or run the handbook marketplace.

The Phase 1 catalog publishing path is GitHub App-backed: calab-sync-agent-primitives-bot reads the calab-ai/apm-registry release catalog artifact and opens PRs to calab-ai/calab-handbook for content/03 Products/Agent Primitives/marketplace/**. It never pushes directly to main, and handbook CI gates apply. This runs in parallel with the .github-private distribution target for generated org-level agent files.

The calab-handbook architecture is:

apm-registry CI (portal-data.json release asset)
    ↓
calab-handbook build (catalog ingest)
    ↓
content/03 Products/Agent Primitives/marketplace/**  (generated pages)
    ↓
Staff marketplace portal

This is sufficient for Phase 1.

Consequences

• The handbook build pipeline fetches portal-data.json from the calab-ai/apm-registry GitHub release assets. No custom API endpoint is needed.
• If a future registry service is created (per the triggers in ADR 011 in apm-registry), the handbook build pipeline will be updated to fetch from that service instead of the release asset. The generated page content and structure will not need to change.
• Architecture documentation in content/03 Products/Agent Primitives/docs/ uses apm-registry as the authoritative source, not a separate service. This is accurate and does not need to be updated unless the architecture changes.
• ADR 011 in apm-registry is the canonical source for deferral criteria and triggers. This decision does not duplicate them; refer to that record for the full list.