Skip to content

Commit 3d9395f

Browse files
Copilotmnriem
Copilot
and
mnriem
authored
feat: add integration catalog system with catalog files, IntegrationCatalog class, list --catalog flag, upgrade command, integration.yml descriptor, and tests
Agent-Logs-Url: https://github.com/github/spec-kit/sessions/bbcd44e8-c69c-4735-adc1-bdf1ce109184 Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>
1 parent 349033e commit 3d9395f

7 files changed

Lines changed: 1808 additions & 1 deletion

File tree

‎integrations/CONTRIBUTING.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Contributing to the Integration Catalog
2+
3+
This guide covers adding integrations to both the **built-in** and **community** catalogs.
4+
5+
## Adding a Built-In Integration
6+
7+
Built-in integrations are maintained by the Spec Kit core team and ship with the CLI.
8+
9+
### Checklist
10+
11+
1. **Create the integration subpackage** under `src/specify_cli/integrations/<name>/`
12+
2. **Implement the integration class** extending `MarkdownIntegration`, `TomlIntegration`, or `SkillsIntegration`
13+
3. **Register the integration** in `src/specify_cli/integrations/__init__.py`
14+
4. **Add tests** under `tests/integrations/test_integration_<name>.py`
15+
5. **Add a catalog entry** in `integrations/catalog.json`
16+
6. **Update documentation** in `AGENTS.md` and `README.md`
17+
18+
### Catalog Entry Format
19+
20+
Add your integration to `integrations/catalog.json`:
21+
22+
```json
23+
{
24+
"my-agent": {
25+
"id": "my-agent",
26+
"name": "My Agent",
27+
"version": "1.0.0",
28+
"description": "Integration for My Agent",
29+
"author": "spec-kit-core",
30+
"repository": "https://github.com/github/spec-kit",
31+
"tags": ["cli"]
32+
}
33+
}
34+
```
35+
36+
## Adding a Community Integration
37+
38+
Community integrations are contributed by external developers and listed in `integrations/catalog.community.json` for discovery.
39+
40+
### Prerequisites
41+
42+
1. **Working integration** — tested with `specify integration install`
43+
2. **Public repository** — hosted on GitHub or similar
44+
3. **`integration.yml` descriptor** — valid descriptor file (see below)
45+
4. **Documentation** — README with usage instructions
46+
5. **License** — open source license file
47+
48+
### `integration.yml` Descriptor
49+
50+
Every community integration must include an `integration.yml`:
51+
52+
```yaml
53+
schema_version: "1.0"
54+
integration:
55+
id: "my-agent"
56+
name: "My Agent"
57+
version: "1.0.0"
58+
description: "Integration for My Agent"
59+
author: "your-name"
60+
repository: "https://github.com/your-name/speckit-my-agent"
61+
license: "MIT"
62+
requires:
63+
speckit_version: ">=0.6.0"
64+
tools:
65+
- name: "my-agent"
66+
version: ">=1.0.0"
67+
required: true
68+
provides:
69+
commands:
70+
- name: "speckit.specify"
71+
file: "templates/speckit.specify.md"
72+
scripts:
73+
- update-context.sh
74+
```
75+
76+
### Descriptor Validation Rules
77+
78+
| Field | Rule |
79+
|-------|------|
80+
| `schema_version` | Must be `"1.0"` |
81+
| `integration.id` | Lowercase alphanumeric + hyphens (`^[a-z0-9-]+$`) |
82+
| `integration.version` | Valid semantic version |
83+
| `requires.speckit_version` | PEP 440 version specifier |
84+
| `provides` | Must include at least one command or script |
85+
| `provides.commands[].name` | String identifier |
86+
| `provides.commands[].file` | Relative path to template file |
87+
88+
### Submitting to the Community Catalog
89+
90+
1. **Fork** the [spec-kit repository](https://github.com/github/spec-kit)
91+
2. **Add your entry** to `integrations/catalog.community.json`:
92+
93+
```json
94+
{
95+
"my-agent": {
96+
"id": "my-agent",
97+
"name": "My Agent",
98+
"version": "1.0.0",
99+
"description": "Integration for My Agent",
100+
"author": "your-name",
101+
"repository": "https://github.com/your-name/speckit-my-agent",
102+
"tags": ["cli"]
103+
}
104+
}
105+
```
106+
107+
3. **Open a pull request** with:
108+
- Your catalog entry
109+
- Link to your integration repository
110+
- Confirmation that `integration.yml` is valid
111+
112+
### Version Updates
113+
114+
To update your integration version in the catalog:
115+
116+
1. Release a new version of your integration
117+
2. Open a PR updating the `version` field in `catalog.community.json`
118+
3. Ensure backward compatibility or document breaking changes
119+
120+
## Upgrade Workflow
121+
122+
The `specify integration upgrade` command supports diff-aware upgrades:
123+
124+
1. **Hash comparison** — the manifest records SHA-256 hashes of all installed files
125+
2. **Modified file detection** — files changed since installation are flagged
126+
3. **Safe default** — modified files are preserved unless `--force` is used
127+
4. **Clean reinstall** — unmodified files are replaced with the latest version
128+
129+
```bash
130+
# Upgrade current integration (blocks if files are modified)
131+
specify integration upgrade
132+
133+
# Force upgrade (overwrites modified files)
134+
specify integration upgrade --force
135+
```

‎integrations/README.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Spec Kit Integration Catalog
2+
3+
The integration catalog enables discovery, versioning, and distribution of AI agent integrations for Spec Kit.
4+
5+
## Catalog Files
6+
7+
### Built-In Catalog (`catalog.json`)
8+
9+
Contains integrations that ship with Spec Kit. These are maintained by the core team and always installable.
10+
11+
### Community Catalog (`catalog.community.json`)
12+
13+
Community-contributed integrations. Listed for discovery only — users install from the source repositories.
14+
15+
## CLI Commands
16+
17+
```bash
18+
# List built-in integrations (default)
19+
specify integration list
20+
21+
# Browse full catalog (built-in + community)
22+
specify integration list --catalog
23+
24+
# Install an integration
25+
specify integration install copilot
26+
27+
# Upgrade the current integration (diff-aware)
28+
specify integration upgrade
29+
30+
# Upgrade with force (overwrite modified files)
31+
specify integration upgrade --force
32+
```
33+
34+
## Integration Descriptor (`integration.yml`)
35+
36+
Each integration can include an `integration.yml` descriptor that documents its metadata, requirements, and provided commands/scripts:
37+
38+
```yaml
39+
schema_version: "1.0"
40+
integration:
41+
id: "my-agent"
42+
name: "My Agent"
43+
version: "1.0.0"
44+
description: "Integration for My Agent"
45+
author: "my-org"
46+
repository: "https://github.com/my-org/speckit-my-agent"
47+
license: "MIT"
48+
requires:
49+
speckit_version: ">=0.6.0"
50+
tools:
51+
- name: "my-agent"
52+
version: ">=1.0.0"
53+
required: true
54+
provides:
55+
commands:
56+
- name: "speckit.specify"
57+
file: "templates/speckit.specify.md"
58+
- name: "speckit.plan"
59+
file: "templates/speckit.plan.md"
60+
scripts:
61+
- update-context.sh
62+
- update-context.ps1
63+
```
64+
65+
## Catalog Schema
66+
67+
Both catalog files follow the same JSON schema:
68+
69+
```json
70+
{
71+
"schema_version": "1.0",
72+
"updated_at": "2026-04-08T00:00:00Z",
73+
"catalog_url": "https://...",
74+
"integrations": {
75+
"my-agent": {
76+
"id": "my-agent",
77+
"name": "My Agent",
78+
"version": "1.0.0",
79+
"description": "Integration for My Agent",
80+
"author": "my-org",
81+
"repository": "https://github.com/my-org/speckit-my-agent",
82+
"tags": ["cli"]
83+
}
84+
}
85+
}
86+
```
87+
88+
### Required Fields
89+
90+
| Field | Type | Description |
91+
|-------|------|-------------|
92+
| `schema_version` | string | Must be `"1.0"` |
93+
| `updated_at` | string | ISO 8601 timestamp |
94+
| `integrations` | object | Map of integration ID → metadata |
95+
96+
### Integration Entry Fields
97+
98+
| Field | Type | Required | Description |
99+
|-------|------|----------|-------------|
100+
| `id` | string | Yes | Unique ID (lowercase alphanumeric + hyphens) |
101+
| `name` | string | Yes | Human-readable display name |
102+
| `version` | string | Yes | Semantic version |
103+
| `description` | string | Yes | One-line description |
104+
| `author` | string | No | Author name or organization |
105+
| `repository` | string | No | Source repository URL |
106+
| `tags` | array | No | Searchable tags (e.g., `["cli", "ide"]`) |
107+
108+
## Contributing
109+
110+
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add integrations to the community catalog.

‎integrations/catalog.community.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"schema_version": "1.0",
3+
"updated_at": "2026-04-08T00:00:00Z",
4+
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.community.json",
5+
"integrations": {}
6+
}

0 commit comments

Comments
 (0)