Concepts

Primitives

A primitive is the smallest independently installable unit in APM. Each primitive is a single file or folder defining one of the following types:

Type	Description
agents	Copilot agent instruction files
instructions	Shared coding or workflow instructions
prompts	Reusable prompt templates
skills	gh-calab skill definitions
hooks	Lifecycle hook scripts
init	Repository initialisation sequences

Primitives are addressed by their APM ID (e.g., calab.agent.build) and versioned independently.

Packages

A package is a curated bundle of primitives that are installed together. Packages provide a coherent capability set — for example, calab.package.workspace-base installs build and plan agents, coding-standards and security instructions, and essential CLI skills.

gh calab apm install package calab.package.workspace-base

Lockfile

After installation, APM writes apm.lock.yaml to your repository root. The lockfile records:

• Every installed primitive and package (with exact versions)
• Source registry and apm_ref for provenance
• Checksums for integrity verification

Never edit the lockfile manually. Use gh calab apm update to upgrade.

Provenance

Each primitive and package in the registry has an apm_ref field pointing to the exact artifact in calab-ai/apm-registry. This enables:

• Reproducible installs
• Audit trails
• Rollback via gh calab apm install --version <ver>