You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`context_file`| Class attribute (str or None) | Path to agent context/instructions file (e.g., `"CLAUDE.md"`, `".github/copilot-instructions.md"`) |
154
150
155
151
**Key design rule:** For CLI-based integrations (`requires_cli: True`), `key` must be the actual executable name (e.g., `"cursor-agent"` not `"cursor"`). This ensures `shutil.which(key)` works for CLI-tool checks without special-case mappings. IDE-based integrations (`requires_cli: False`) should use their canonical identifier (e.g., `"windsurf"`, `"copilot"`).
Set `context_file` on the integration class. The base integration setup creates or updates the managed Spec Kit section in that file, and uninstall removes the managed section when appropriate.
174
+
The Specify CLI carries **no agent-context state whatsoever**. Integration classes do **not** declare a `context_file`, and the CLI never creates, updates, removes, resolves, or migrates a context/instruction file (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, …). New integrations add nothing for context handling.
179
175
180
-
The managed section is owned by the bundled `agent-context` extension (`extensions/agent-context/`). All configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml`:
176
+
Managing the "Spec Kit" section in the context file is fully owned by the bundled `agent-context` extension (`extensions/agent-context/`), which is a **full opt-in**: `specify init` does not install it. A user adds/enables it through the standard extension verbs, after which the extension's own bundled scripts maintain the context section. When the extension is absent or disabled, nothing in Spec Kit touches the context file.
177
+
178
+
The extension reads its own config file at `.specify/extensions/agent-context/agent-context-config.yml`:
181
179
182
180
```yaml
183
181
# Path to the coding agent context file managed by this extension
@@ -189,10 +187,10 @@ context_markers:
189
187
end: "<!-- SPECKIT END -->"
190
188
```
191
189
192
-
- `context_file` is written automatically from the integration's class attribute when `specify init` or `specify integration use` is run.
193
-
- `context_markers.{start,end}`defaults to `IntegrationBase.CONTEXT_MARKER_START` / `CONTEXT_MARKER_END`. Users who want custom markers edit `agent-context-config.yml` directly — both the Python layer (`upsert_context_section()` / `remove_context_section()`) and the bundled scripts (`extensions/agent-context/scripts/bash/update-agent-context.sh` and `.ps1`) read from this single source of truth.
190
+
- The Specify CLI does **not** write this config. When `context_file` is empty, the extension's bundled scripts self-seed it by looking up the active integration's key in the extension's own `agent-context-defaults.json` map (`extensions/agent-context/scripts/bash/update-agent-context.sh` and `.ps1`). The CLI registry is never consulted — all agent→context-file knowledge lives inside the extension.
191
+
- `context_markers.{start,end}`are read solely by the extension's scripts; they default to the Spec Kit markers shown above and can be customized by editing `agent-context-config.yml` directly.
194
192
195
-
Users can opt out entirely with `specify extension disable agent-context`; while disabled, Spec Kit skips context-file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
193
+
Existing projects created by older Spec Kit versions keep working: any previously written managed section or extension config is left intact and is only ever updated by the extension when run.
196
194
197
195
Only add custom setup logic when the agent needs non-standard behavior. Integrations no longer require per-agent thin wrapper scripts or shared context-update dispatcher scripts — the `agent-context` extension is fully generic.
198
196
@@ -401,7 +399,6 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):
401
399
2. Extracts title and description from frontmatter
4. Uses `yaml.safe_dump()` for header fields to ensure proper escaping
404
-
5. Sets `context_file = "AGENTS.md"` so the base setup manages the Spec Kit context section there
405
402
406
403
## Branch Naming Convention
407
404
@@ -466,7 +463,7 @@ Disclosure is **continuous**, not a one-time event. A single AI-disclosure parag
466
463
## Common Pitfalls
467
464
468
465
1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), the `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks — mismatches require special-case mappings. IDE-based integrations (`requires_cli: False`) are not subject to this constraint.
469
-
2. **Forgetting context configuration**: The bundled `agent-context` extension reads from `.specify/extensions/agent-context/agent-context-config.yml`. New integrations only need to set `context_file` on the class — markers and dispatcher scripts are managed centrally.
466
+
2. **Reintroducing context handling into the CLI**: The opt-in `agent-context` extension owns everything about context files — including the per-agent default mapping in `agent-context-defaults.json`. Integration classes must **not** declare a `context_file`, and no CLI code should read, write, resolve, or migrate context files. All context-file logic lives in `.specify/extensions/agent-context/` and its bundled scripts.
470
467
3. **Incorrect `requires_cli` value**: Set to `True` only for agents that have a CLI tool; set to `False` for IDE-based agents.
471
468
4. **Wrong argument format**: Use `$ARGUMENTS` for Markdown agents, `{{args}}` for TOML agents.
472
469
5. **Skipping registration**: The import and `_register()` call in `_register_builtins()` must both be added.
The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi, Oh My Pi, Forge, Goose, Mistral Vibe, or ZCode installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
409
+
The CLI will check that your selected agent's CLI tool is installed (for integrations that require a CLI), such as Claude Code, Gemini CLI, Qwen Code, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi Coding Agent, Oh My Pi, Forge, Goose, Mistral Vibe, or ZCode. If you don't have the required tool installed, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
|[Codex CLI](https://github.com/openai/codex)|`codex`| Skills-based integration; installs skills into `.agents/skills` and invokes them as `$speckit-<command>`|
16
16
|[Cursor](https://cursor.sh/)|`cursor-agent`||
17
17
|[Devin for Terminal](https://cli.devin.ai/docs)|`devin`| Skills-based integration; installs skills into `.devin/skills/` and invokes them as `/speckit-<command>`|
18
18
|[Firebender](https://firebender.com/)|`firebender`| IDE-based agent for Android Studio / IntelliJ |
@@ -54,6 +54,27 @@ Shows all available integrations, which one is currently installed, and whether
54
54
When multiple integrations are installed, the list marks the default integration separately from the other installed integrations.
55
55
The list also shows whether each built-in integration is declared multi-install safe.
56
56
57
+
## Search Available Integrations
58
+
59
+
```bash
60
+
specify integration search [query]
61
+
```
62
+
63
+
| Option | Description |
64
+
| ---------- | ------------------ |
65
+
|`--tag`| Filter by tag |
66
+
|`--author`| Filter by author |
67
+
68
+
Searches the active catalog stack for integrations matching the query. Without a query, lists all available integrations. Must be run inside a Spec Kit project.
69
+
70
+
## Integration Info
71
+
72
+
```bash
73
+
specify integration info <integration_id>
74
+
```
75
+
76
+
Shows catalog details for a single integration, including its description, author, license, tags, source catalog, repository (when available), and whether it is currently active. Must be run inside a Spec Kit project.
77
+
57
78
## Install an Integration
58
79
59
80
```bash
@@ -152,6 +173,47 @@ is `null` when no installed integration set can be evaluated, such as when the
152
173
integration state is missing, unreadable, lacks a valid recorded integration
153
174
list, or records no installed integrations.
154
175
176
+
## Catalog Management
177
+
178
+
Integration catalogs control where the discovery commands (`search` and `info`) look for integrations. Catalogs are checked in priority order.
179
+
180
+
### List Catalogs
181
+
182
+
```bash
183
+
specify integration catalog list
184
+
```
185
+
186
+
Shows the active catalog sources. Project-level sources (when configured) are removable by index; otherwise the active sources are shown as non-removable.
Adds a custom catalog URL to the project's `.specify/integration-catalogs.yml`. The URL must use HTTPS (except `http://localhost`, `http://127.0.0.1`, or `http://[::1]` for local testing).
199
+
200
+
### Remove a Catalog
201
+
202
+
```bash
203
+
specify integration catalog remove <index>
204
+
```
205
+
206
+
Removes a project catalog source by its 0-based index in `catalog list`.
207
+
208
+
### Catalog Resolution Order
209
+
210
+
Catalogs are resolved in this order (first match wins):
211
+
212
+
1.**Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs
Creates a minimal built-in integration package and a matching test skeleton in the Spec Kit repository, then prints the next steps for wiring it up. Run this command from the Spec Kit repository root. The `<key>` must be lowercase kebab-case (for example, `my-agent`).
0 commit comments