Calab.ai Handbook

Graph View

APM Sequence Diagrams

3 min read

Edit this page

APM Sequence Diagrams

These sequence diagrams document the key operational flows for the Agent Package Manager (APM) ecosystem.

Source .mmd files live alongside this document under docs/sequences/.

1. Release to Marketplace Flow

Shows how a platform maintainer publishes primitives or packages from apm-registry, how the catalog release artifacts are generated, and how both the calab-handbook marketplace and gh calab CLI consume those artifacts.

sequenceDiagram
    autonumber
    participant Maintainer as Platform Maintainer
    participant Source as apm-registry
    participant CI as Release CI
    participant Catalog as Catalog Release Artifacts
    participant Handbook as calab-handbook
    participant CLI as gh calab

    Maintainer->>Source: Open PR with primitive/package changes
    Source->>CI: Merge to main triggers validation
    CI->>CI: Validate schemas, metadata, packages, policies
    CI->>Catalog: Publish RC primitive/package tags and catalog artifacts
    Maintainer->>CI: Approve and publish GA release
    CI->>Catalog: Publish immutable GA tags and catalog artifacts
    Handbook->>Catalog: Fetch portal-data.json and search index
    Catalog-->>Handbook: Return portal-data.json and search index
    Handbook->>Handbook: Build staff marketplace pages
    Catalog-->>CLI: Serve catalog for gh calab apm resolution

2. Consumer Install and Update Flow

Shows how Calab staff use gh calab apm install to declare package dependencies, resolve the catalog, write lockfiles with immutable tag refs, and generate target files. Consumer CI then validates the installed state for drift.

sequenceDiagram
    autonumber
    participant Staff as Calab Staff
    participant CLI as gh calab apm
    participant Repo as Consumer Repository
    participant Manifest as apm.yml
    participant Catalog as Released Catalog
    participant Lock as apm.lock.yaml
    participant Files as Generated Tool Files
    participant CI as Consumer CI

    Staff->>CLI: gh calab apm install calab-workspace-base
    CLI->>Repo: Locate repository root
    CLI->>Manifest: Add or update desired package dependency
    CLI->>Catalog: Resolve latest compatible GA tag graph
    Catalog-->>CLI: Return packages, primitives, tag refs, hashes, compatibility
    CLI->>Lock: Write exact tags, resolved commits, hashes
    CLI->>Files: Generate .github/.claude/.opencode/.codex/.workspace files
    CLI->>Repo: Write .generated-from-apm.json provenance
    Staff->>Repo: Commit manifest, lockfile, generated files
    CI->>CLI: gh calab apm validate --ci
    CLI-->>CI: Pass or fail on drift, unmanaged files, mutable refs

3. Upstream Ingestion Flow

Shows how a platform maintainer imports approved external content (e.g. from github/awesome-copilot) into apm-registry using gh calab apm import, with policy enforcement via upstream.config.json and lockfile provenance.

sequenceDiagram
    autonumber
    participant Maintainer as Platform Maintainer
    participant CLI as gh calab apm import
    participant Config as upstream.config.json
    participant External as Approved External Source
    participant Source as apm-registry
    participant Lock as apm.lock.yaml
    participant PR as GitHub PR

    Maintainer->>Config: Declare approved source paths and target paths
    Maintainer->>CLI: gh calab apm import --source github/awesome-copilot
    CLI->>Config: Read import rules and source allowlist
    CLI->>External: Fetch files at approved tag or resolved commit
    External-->>CLI: Return matching files and source metadata
    CLI->>Source: Write vendored files into governed source tree
    CLI->>Lock: Record source repo, tag/ref, resolved commit, file hashes
    CLI->>Source: Write generated provenance metadata
    Maintainer->>PR: Open PR with imported changes and lockfile
    PR->>PR: CI validates hashes, mappings, safe deletion, policy

4. .github-private Distribution Flow

Shows how a GA release from apm-registry triggers the distribution workflow that synchronises generated org-level Copilot agents into .github-private via a validated auto-merge PR.

sequenceDiagram
    autonumber
    participant Release as apm-registry GA Release
    participant Workflow as Distribution Workflow
    participant Dist as Generated Distribution
    participant Private as .github-private
    participant Validation as .github-private Validation
    participant Org as GitHub Org Copilot Surface

    Release->>Workflow: GA tag published
    Workflow->>Dist: Fetch calab-org-agents package output
    Dist-->>Workflow: Return generated agent files and metadata
    Workflow->>Private: Open or update generated sync PR
    Workflow->>Private: Write agents and .generated-from-apm.json
    Private->>Validation: Validate generated files, source refs, hashes
    Validation-->>Private: Approve auto-merge if no drift
    Private->>Org: Expose generated org-level Copilot agents

Backlinks

Graph View

Graph View