11 APM CLI Direction

Status

Accepted

Context

The existing GitHub CLI extension calab-ai/gh-agent-primitives was created to provide gh agent-primitives ... commands for working with agent primitives. As the APM model has expanded to cover full package management and workspace tooling, the CLI needs to:

• support a broader gh calab command surface beyond agent primitives
• align the command prefix with the Calab.ai brand rather than a specific product
• support gh calab apm install, gh calab apm sync, gh calab apm validate, and related subcommands

The existing extension cannot provide gh calab ... commands without being renamed. GitHub CLI extension naming follows the convention that the extension binary name matches the command invocation: a repository named gh-calab provides gh calab.

Decision

The authoritative GitHub CLI extension repository is calab-ai/gh-calab, providing gh calab apm ... commands.

The existing calab-ai/gh-agent-primitives extension is retained as a compatibility shim for one major release cycle. It should forward to gh calab apm equivalents where feasible and display a deprecation notice on invocation.

The target command surface is:

gh calab doctor
gh calab apm catalog
gh calab apm install <package>
gh calab apm resolve
gh calab apm sync
gh calab apm validate
gh calab apm lock
gh calab apm update
gh calab apm uninstall
gh calab apm import
gh calab workspace init

Consequences

• All APM CLI documentation and sequence diagrams use gh calab apm ... as the canonical form.
• Staff who have installed gh-agent-primitives must migrate to gh-calab within the deprecation window.
• The gh-agent-primitives repository must publish a deprecation notice and point users to the migration guide.
• New CLI features are developed only in gh-calab; no new functionality is added to gh-agent-primitives after the shim release.
• CI pipelines and handbook content that reference gh agent-primitives must be updated to gh calab apm equivalents.