The integration catalog enables discovery, versioning, and distribution of AI agent integrations for Spec Kit.

Contains integrations that ship with Spec Kit. These are maintained by the core team and always installable.

Community-contributed integrations. The default community source is discovery-only: listing an adapter is neither installation permission nor a code audit. Review external code before using an install-enabled catalog.

The catalog stack is resolved in this order (first match wins):

1. Environment variable — SPECKIT_INTEGRATION_CATALOG_URL overrides all catalogs with a single URL
2. Project config — .specify/integration-catalogs.yml in the project root
3. User config — ~/.specify/integration-catalogs.yml in the user home directory
4. Built-in defaults — catalog.json + catalog.community.json

Example integration-catalogs.yml:

catalogs:
  - url: "https://example.com/my-catalog.json"
    name: "my-catalog"
    priority: 1
    install_allowed: true

# List built-in and trusted installed integrations
specify integration list

# Browse full catalog (built-in + community)
specify integration list --catalog

# Install an integration
specify integration install copilot

# Register a reviewed private catalog and install its external adapter
specify integration catalog add https://example.com/catalog.json --name samples
specify integration install sample-agent

# Non-interactive install, after reviewing and trusting the adapter
specify integration install sample-agent --trust-integration

# Make an installed adapter the default
specify integration use sample-agent

# Upgrade the current integration (diff-aware)
specify integration upgrade

# Upgrade with force (overwrite modified files)
specify integration upgrade --force

Each external integration package includes an adapter-only integration.yml descriptor and a root __init__.py exporting an IntegrationBase subclass. No command inventory or copied core templates are needed:

schema_version: "1.0"
integration:
  id: "sample-agent"
  name: "Sample Agent"
  version: "1.0.0"
  description: "Adapter for Sample Agent"
  license: "MIT"
requires:
  speckit_version: ">=1.1.2.dev0"
  tools:
    - name: "sample-agent"
      required: true

requires.tools is optional; omit it for adapters with no required executable. Optional legacy provides metadata remains valid but does not supply host commands. See integration design for class metadata, runtime methods, tools, and storage requirements.

Both catalog files follow the same JSON schema:

{
  "schema_version": "1.0",
  "updated_at": "2026-04-08T00:00:00Z",
  "catalog_url": "https://...",
  "integrations": {
    "sample-agent": {
      "id": "sample-agent",
      "name": "Sample Agent",
      "version": "1.0.0",
      "description": "Adapter for Sample Agent",
      "download_url": "https://example.com/sample-agent/1.0.0/sample-agent.zip",
      "tags": ["cli"]
    }
  }
}

The map key and any declared id must match integration.id. Name, version, description, and optional author/repository/license metadata must match the descriptor. Built-in entries need no download fields because their implementations ship with the CLI.

Registering a catalog with integration catalog add creates an install-enabled project source. Set install_allowed: false in its configuration to permit discovery only. This policy cannot be overridden with --trust-integration or --force. Each external install/update prompts before downloading/importing Python unless explicitly pre-authorized with --trust-integration. Authenticated GitHub assets use the existing Spec Kit authentication providers.

Installed code is stored in .specify/integrations/packages/<id>/ with provenance and hashes in packages.json; both are excluded by the managed .specify/.gitignore. Execution consent is stored separately in ~/.specify/integration-trust.json, bound to the canonical project root, integration ID, and verified package digest. Project metadata cannot grant consent. Copying a project or changing users requires a new local decision: review the package and run specify integration upgrade sample-agent --force --trust-integration from an install-enabled catalog. Generated files have a separate hash-tracked <id>.manifest.json; new CLI processes load the trusted package without fetching the catalog. An upgrade fetches the catalog's current version and checks its descriptor again. Do not edit installed package code in place: publish a new archive/version and upgrade instead. Catalog management/discovery and integration info remain metadata-only and do not import adapters. Forced upgrade/uninstall can recover damaged installed code using user-local registrar and generated-path ownership records, without bypassing source policy or trust. Edited project cleanup claims are rejected. Without local ownership proof, old-only generated files are preserved with a manual-cleanup warning; trusted replacement setup still targets its declared destination. Concurrent dispatch pins each project's adapter and verified imports independently.

See CONTRIBUTING.md for how to add integrations to the community catalog.