Integration catalog — built-in and community integration discovery and distribution

[mnriem]

Summary

Add a catalog system for integrations, mirroring the existing extension and preset catalog patterns. This enables discovery, versioning, and community-contributed integrations.

Motivation

With the integration architecture from #1924 and the specify integration subcommand from #2065, integrations become self-contained packages. A catalog system enables community distribution and discoverability — the same way extensions and presets already work.

Proposed Commands

specify integration list --catalog          # browse full catalog (built-in + community)
specify integration install acme-coder      # install from catalog
specify integration install ./local/path    # install from local directory
specify integration upgrade copilot         # diff-aware via manifest hashes

Catalog Structure

Follow the established pattern from extensions/catalog.json and presets/catalog.json:

{
  "schema_version": "1.0",
  "updated_at": "2026-04-02T00:00:00Z",
  "catalog_url": "https://...",
  "integrations": {
    "my-agent": {
      "id": "my-agent",
      "name": "My Agent",
      "version": "1.0.0",
      "description": "Integration for My Agent",
      "author": "my-org",
      "repository": "https://github.com/my-org/speckit-my-agent",
      "download_url": "https://...",
      "requires": { "speckit_version": ">=0.6.0" },
      "tags": ["cli"]
    }
  }
}

Integration Descriptor

integration.yml — mirrors the extension.yml and preset.yml patterns:

schema_version: "1.0"
integration:
  id: "my-agent"
  name: "My Agent"
  version: "1.0.0"
  description: "Integration for My Agent"
  author: "my-org"
  repository: "https://github.com/my-org/speckit-my-agent"
  license: "MIT"
requires:
  speckit_version: ">=0.6.0"
  tools:
    - name: "my-agent"
      version: ">=1.0.0"
      required: true
provides:
  commands:
    - name: "speckit.specify"
      file: "templates/speckit.specify.md"
    - name: "speckit.plan"
      file: "templates/speckit.plan.md"
  scripts:
    - update-context.sh
    - update-context.ps1

Deliverables

• integrations/catalog.json — built-in integrations metadata
• integrations/catalog.community.json — community-contributed integrations
• integration.yml descriptor (mirrors extension.yml / preset.yml)
• Version pinning and compatibility checks
• Diff-aware upgrades via manifest hash comparison
• Developer guide for adding both built-in and community integrations (checklist, descriptor spec, publishing workflow)

Depends on

• From Agents to Integrations #1924 (integration architecture + manifest system)
• Add specify integration subcommand for post-init integration management #2065 (specify integration subcommand)

Acceptance Criteria

• integrations/catalog.json and integrations/catalog.community.json follow established catalog schema
• specify integration list --catalog shows built-in and community integrations
• Install from catalog creates correct files + manifest
• specify integration upgrade detects version changes, handles modified files via manifest hashes
• integration.yml descriptor documented and validated
• Community catalog contribution workflow documented
• Developer guide covers adding both built-in and community integrations
• Invalid/missing catalog entries produce clear errors