74662cffad
* feat: update Bob integration to skills-based layout for Bob 2.0 Bob 2.0 replaces the command-based workflow (.bob/commands/*.md) with a skills-based layout (.bob/skills/speckit-<name>/SKILL.md), matching the pattern used by Claude Code, Codex, and other skills-first agents. - Switch BobIntegration from MarkdownIntegration to SkillsIntegration - Update folder/dir from .bob/commands to .bob/skills - Change extension from .md to /SKILL.md (skills layout) - Add --skills option (default: True) consistent with Codex pattern - Update tests to inherit from SkillsIntegrationTests (28 tests pass) - Bump catalog entry to version 2.0.0 with updated description Assisted-by: IBM Bob (model: claude-sonnet-4-5, autonomous) * PR comments fix: keep old Bob 1 commands till next release * Copilot suggested change Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * feat(bob): address copilot comments, make skills layout default, demote legacy commands to opt-in * fix(bob): honor legacy_commands in ai_skills persistence and add bob to ALWAYS_SLASH_AGENTS - init.py: suppress ai_skills=True when --legacy-commands is passed so extensions and presets target .bob/commands, not .bob/skills - _invocation_style.py: add 'bob' to ALWAYS_SLASH_AGENTS so init next-steps and hook invocations always show /speckit-<name> (skills is the default layout; no ai_skills flag required) * Copilot suggestion Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * fix(bob): extend IntegrationBase directly to avoid false isinstance(SkillsIntegration) - bob/__init__.py: switch BobIntegration base from SkillsIntegration to IntegrationBase; add _BobSkillsHelper for skills-mode delegation; set invoke_separator='-' explicitly; set _skills_mode flag in setup() so consumers can derive the effective mode without isinstance checks - _helpers.py: replace isinstance(integration, SkillsIntegration) guard with getattr(_skills_mode) so legacy-commands mode does not persist ai_skills=True - _invocation_style.py: remove 'bob' from ALWAYS_SLASH_AGENTS — Bob 2.0 skills are invoked via natural language, not /skill-name slash commands - integrations/catalog.json: advance updated_at to 2026-07-15 * fix(lint): remove unused SkillsIntegration import from _helpers.py * Copilot suggested change Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * feat(bob): add bob skills integration with registrar-based mode detection * address 3 comments from copilot * feat(bob): update registrar config to use legacy commands layout * fix lint * Suggested fix from Copilot Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * fix pr comment * fix pr comment * fix pr comment * refactor(bob): resolve skills mode via base-class hooks + fix command-ref separators Rework the dual-mode handling introduced for Bob 2.0 so an integration's internal representation never leaks into shared init/install/upgrade code, and fix the legacy command-reference separator surfaced in review. Base-class contract: - Add IntegrationBase.is_skills_mode(parsed_options) — the single hook the shared machinery consults to decide whether to persist ai_skills and render skill invocations. SkillsIntegration returns True; Copilot honors --skills / self._skills_mode; Bob returns `not legacy_commands`. - Add IntegrationBase.invoke_separator_for_mode(skills_enabled) — resolves the command-ref separator from a project's persisted mode for registration paths that only have the ai_skills flag (no CLI parsed_options). Default is behavior-preserving; Bob maps skills->"-", legacy->".". - BobIntegration stays on IntegrationBase (mirroring Copilot, the other dual-mode agent) and delegates setup() to internal _BobSkillsHelper / _BobMarkdownHelper. Removes the _skills_mode method and all isinstance(SkillsIntegration) / callable(_skills_mode) probing from _helpers.py and init.py. Fix legacy separator (review feedback): CommandRegistrar.register_commands and PresetManager._resolve_skill_command_refs previously read the single static AGENT_CONFIGS[key]["invoke_separator"], so legacy .bob/commands/ extension and preset command refs rendered /speckit-<cmd> instead of Bob 1.x /speckit.<cmd>. Both now resolve the separator per project mode via invoke_separator_for_mode. Tests: add regression coverage for the is_skills_mode / invoke_separator_for_mode hooks and legacy extension command-ref separators; normalize a width-sensitive workflow assertion to match its siblings. Full suite green. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob,copilot): address review — preserve legacy layout, dual-mode separators, extension-skill token resolution Addresses PR review 4716036212 (3 comments): 1. Bob legacy-install regression: `use`/`switch`/`upgrade` on an existing Bob 1.x project (only `.bob/commands/` on disk, no stored `legacy_commands`) called `is_skills_mode(None)` -> True and rewrote `ai_skills=True`, silently switching extension/command-reference handling to the skills layout. `is_skills_mode` now takes an optional `project_root`; Bob preserves an already-installed legacy layout until an explicit upgrade creates `.bob/skills/`. A fresh project still defaults to skills. 2. Copilot dual-mode separator: `invoke_separator_for_mode` was inherited from the base (mode-independent) and returned Copilot's static `.`, so preset/extension command refs in a Copilot skills project rendered `/speckit.<name>` instead of `/speckit-<name>`. Override it on Copilot to track the persisted `ai_skills` state, consistent with `build_command_invocation` and `effective_invoke_separator`. 3. Bob extension-skill command-ref tokens: verified that merging main's generic `_resolve_command_ref_tokens` (#3544) resolves Bob's tokens via the `CONDITIONAL_SLASH_AGENTS` path (`/speckit-<name>`); added Bob to the command-ref regression parametrize plus dedicated Bob use-path tests. All tests pass (full suite green; merged with current main incl. #3544). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): resolve command-ref separator with project-aware mode before shared-infra refresh (review #3415) The `use`/`switch` paths refresh shared infrastructure via `_with_integration_setting()` / `_invoke_separator_for_integration()`, which previously resolved the invoke separator through `effective_invoke_separator` / `is_skills_mode` WITHOUT a project_root. For a pre-PR Bob 1.x project (.bob/commands/ on disk, no stored options), this defaulted to the skills "-" separator and rewrote rendered shared-template command refs to /speckit-*, even though ai_skills stayed false. Thread project_root through effective_invoke_separator, the two runtime helpers, and every call site so Bob's on-disk legacy detection governs the separator before shared infra is refreshed. Add a rendered-shared-template regression test covering `use --force`. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): scope persisted ai_skills flag to active agent when resolving command-ref separator (review #3415) `register_commands` runs once per detected agent, but the persisted `ai_skills` flag describes only the active integration (`opts["ai"]`). When another agent (e.g. Copilot) is active in skills mode while a legacy `.bob/commands` layout is also present, the previous code passed that global `True` to Bob's `invoke_separator_for_mode`, rewriting Bob 1.x command refs to `/speckit-*` instead of `/speckit.*`. Only consult the persisted flag for the agent it describes (`opts["ai"] == agent_name`); otherwise resolve the separator from the agent's own project-aware `effective_invoke_separator(None, project_root)`. Add regression tests covering the mismatched-active-agent case and a control for Bob-active skills mode. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): detect Spec Kit layout from managed artifacts, not any skills dir (review #3415) Two related mis-detections from review 4723246468: 1. `BobIntegration.is_skills_mode` treated the mere presence of a `.bob/skills/` directory as proof the project is skills-based. A legacy Spec Kit install (managed `.bob/commands/speckit.*.md`) that also carried unrelated Bob 2 skills would be misclassified as skills, so `integration use bob` persisted `ai_skills` and rewrote shared refs. Now the layout is inferred from managed Spec Kit artifacts: legacy/command mode only when managed `speckit.*.md` command files exist and no managed `speckit-*` skill dirs do. 2. The `register_commands` separator for an inactive agent used a disk-based `effective_invoke_separator(None, project_root)` fallback that could pick the skills separator even though the registrar writes the static command layout (`.bob/commands/*.md`). Inactive agents now resolve the separator from the registrar's actual output layout (`extension == "/SKILL.md"`), so command-layout files keep `/speckit.*` refs regardless of sibling dirs. Update the affected hook/E2E tests to use managed artifacts and add regression tests for the mixed-layout and inactive-registrar scenarios. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): apply managed-artifact detection on upgrade + consistent skill post-processing (review #3415) Two issues from review 4723782860: 1. `BobIntegration.setup()` resolved the layout via `is_skills_mode(parsed_options)` WITHOUT `project_root`, so `integration upgrade bob` on a Bob 1.x install (managed `.bob/commands/speckit.*.md`, no stored options) ignored the existing command files, generated skills, and stale-deleted the legacy commands — silently migrating the project. Pass `project_root` so the same managed-artifact detection used by `use` also governs upgrades. 2. Only `_BobSkillsHelper` overrode `post_process_skill_content` to suppress the shared slash-command hook note. Preset/extension skill generators call that hook on the registered `BobIntegration`, which inherited `IntegrationBase`'s note-injecting default. Repeat the no-op (delegating to the skills helper) on the registered class so every Bob skill-generation path is consistent with intent-activated core Bob skills. Add regression tests for the upgrade-preservation and post-processing paths. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * feat(bob): add --skills migration opt-in; fix separator + manifest loss (review #3415) Address review #3415 (4724160183): - Comment 1: Add an explicit `--skills` opt-in to BobIntegration. It forces the skills layout over on-disk auto-detection, giving legacy Bob 1.x installs a supported migration path (`integration upgrade bob --integration-options="--skills"`). `--skills` and `--legacy-commands` are mutually exclusive (clean exit-1 error). - Comment 2: In CommandRegistrar.register_commands, derive the command-ref separator from the output layout (agent_config["extension"]) for the active agent too, not the persisted ai_skills flag. A command-layout file (.bob/commands/*.md, .github/agents/*.agent.md) always renders /speckit.*; only a /SKILL.md scaffold uses /speckit-*. Dual-layout agents (Bob, Copilot) write skills via their own setup()/skills path, so register_commands only ever emits their command-layout files. - Comment 3: Update docs/reference/integrations.md Bob entry to document the skills-based default (.bob/skills/), the deprecated --legacy-commands opt-out, and the --skills migration path. Also fix a latent manifest-loss bug surfaced by the migration path: the upgrade Phase 2 stale-file cleanup built a throwaway manifest sharing the integration key and called uninstall(), which always deleted {key}.manifest.json. Any layout-shrinking upgrade (e.g. legacy->skills) thus wiped the freshly-saved manifest, leaving the project untracked and un-upgradeable. uninstall() now takes remove_manifest (default True); the stale-cleanup pass passes False. Adds regression tests for the --skills opt-in, mutual exclusion, corrected active-agent separator, remove_manifest=False, and an end-to-end legacy->skills migration that verifies the manifest survives and the project remains upgradeable. Full suite: 4555 passed, 5 skipped. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * docs(agents): align token-resolution comment with output-layout separator rule (review #3415) Address review #3415 (4725516805). The comment above resolve_command_refs still described the removed state-based behavior ("resolve it from the integration using the project's persisted skills state"). Update it to describe the output-layout rule that register_commands now uses: _sep is derived from the layout this registrar writes (a /SKILL.md scaffold uses the skills separator; a command-layout file uses the command separator), not the persisted ai_skills state. Comment-only change; no behavior change. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): reconcile extension artifacts on layout change (review #3415) When a dual-mode agent (Bob) flips between the legacy commands layout and the skills layout during `integration upgrade` (via `--skills` / `--legacy-commands`), the old layout's extension command/skill files were left orphaned: Phase 2 stale cleanup only removes files tracked by the *integration* manifest, while extension artifacts are tracked in the extension registry. Detect the layout flip by comparing whether the old vs new manifest tracks a `/SKILL.md` scaffold, and when it changed, unregister the agent's extension artifacts before the existing re-registration so they are recreated in the new layout (and the per-agent registry is updated). Preset artifacts are documented as a known, pre-existing cross-cutting gap: no agent-scoped preset re-registration exists in use/switch/upgrade for any agent, so reconciling them is out of scope for this Bob migration. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): reject layout migration when preset overrides are installed (review #3415) A command↔skills layout change during `integration upgrade` cannot reconcile preset artifacts: presets track their command/skill files in per-preset `registered_commands`/`registered_skills` metadata, and there is no agent-scoped preset re-registration anywhere in the CLI. Migrating would delete a preset's old-layout files without recreating them in the new layout and leave the preset registry claiming artifacts that no longer exist. Detect the intended layout via `is_skills_mode` (so a plain same-layout upgrade is unaffected) and, when it flips while preset overrides are installed for the agent, reject the upgrade *before any mutation* with an actionable error pointing at the remove → upgrade → reinstall workaround. Extension artifacts are still reconciled for the safe (no-preset) case. Adds a regression test and documents the migration caveat in the Bob integration reference entry. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): restrict layout reconciliation to the active integration (review #3415) `integration_upgrade` supports upgrading a secondary (non-active) integration, but the layout-change extension reconciliation was unsafe there. `ExtensionManager.unregister_agent_artifacts()` treats the unscoped per-extension `registered_skills` list as belonging to the passed agent and, when that agent's skills directory is absent, falls back to scanning every agent's skills directory — so reconciling a secondary Bob layout flip could delete or untrack the *active* agent's extension skills. The subsequent re-registration cannot repair that because extension skill rendering is intentionally scoped to the active agent (#2948). Gate the unregister-before-register reconciliation on `installed_key == key` so it only runs for the active integration. Secondary agents only ever have extension command files (skills are active-agent-only), which the existing re-registration rewrites in place, so skipping the unregister orphans nothing new. Adds a regression test asserting a secondary Bob layout change leaves the active agent's extension skill intact on disk and in the registry. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): fail closed when preset registry is unreadable (review #3415) Address review 4744636079: - _migrate_commands: the preset guard previously failed *open* — a registry read/parse error returned an empty "no presets" list, so a --force layout-changing upgrade could delete preset-overridden command files while their registry state was unknown. Read the registry file directly and raise _PresetRegistryUnreadableError on any read/parse failure or malformed structure, rejecting the migration before any mutation. A genuinely absent registry still returns [] (safe). - bob: correct the is_skills_mode docstring — upgrade *does* run setup(); disk detection is needed because legacy Bob 1.x installs never persisted a legacy_commands option, so the stored mode is unavailable. - tests: add fail-closed E2E (corrupted registry rejected, valid-empty allowed) plus a unit test for _installed_presets_affecting_agent covering absent / corrupted / malformed / valid / affecting-agent cases. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf * fix(bob): fail closed on malformed preset entries too (review #3415) Address review 4745191015: the preset guard read a parseable registry but silently skipped malformed per-preset metadata and treated a malformed registered_commands value as "no matching artifacts". A registry such as {"presets":{"p1":[]}} therefore allowed a layout migration even though p1's ownership is unknown, risking deletion of preset-managed files. Now raise _PresetRegistryUnreadableError for a non-dict preset entry, a non-dict registered_commands, or a non-list registered_skills. Extend the unit test to cover these malformed shapes. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
25 KiB
Supported AI Coding Agent Integrations
The Specify CLI supports a wide range of AI coding agents. When you run specify init, the CLI sets up the appropriate command files and directory structures for your chosen AI coding agent — so you can start using Spec-Driven Development immediately, regardless of which tool you prefer.
Supported AI Coding Agents
| Agent | Key | Notes |
|---|---|---|
| Amp | amp |
|
| Antigravity (agy) | agy |
Skills-based integration; skills are installed automatically |
| Auggie CLI | auggie |
|
| Claude Code | claude |
Skills-based integration; installs skills in .claude/skills |
| Cline | cline |
IDE-based agent |
| CodeBuddy CLI | codebuddy |
|
| Codex CLI | codex |
Skills-based integration; installs skills into .agents/skills and invokes them as $speckit-<command> |
| Cursor | cursor-agent |
|
| Devin for Terminal | devin |
Skills-based integration; installs skills into .devin/skills/ and invokes them as /speckit-<command> |
| Firebender | firebender |
IDE-based agent for Android Studio / IntelliJ |
| Forge | forge |
|
| Gemini CLI | gemini |
|
| GitHub Copilot | copilot |
Defaults to legacy markdown mode: .agent.md command files under .github/agents/, companion .prompt.md files under .github/prompts/, and a .vscode/settings.json merge. Pass --integration-options="--skills" to scaffold skills as speckit-<command>/SKILL.md under .github/skills/ instead. Legacy markdown mode is deprecated and will stop being the default in a future release. |
| Goose | goose |
Uses YAML recipe format in .goose/recipes/ |
| Grok Build | grok |
Skills-based integration; installs skills into .grok/skills and invokes them as /speckit-<command> |
| Hermes | hermes |
Skills-based integration; installs skills globally into ~/.hermes/skills/ |
| IBM Bob | bob |
Skills-based integration by default; installs skills as speckit-<command>/SKILL.md under .bob/skills/ and invokes them as /speckit-<command>. Pass --integration-options="--legacy-commands" to scaffold the deprecated Bob 1.x layout (.bob/commands/*.md) instead; that flag will be removed in a future release. Existing legacy installs can migrate with specify integration upgrade bob --integration-options="--skills", which converts them to the skills layout and removes the old command files. If preset overrides are installed, the migration is rejected with an actionable error (preset artifacts cannot yet be reconciled across a layout change) — remove the preset(s), migrate, then reinstall them. |
| Junie | junie |
|
| Kilo Code | kilocode |
|
| Kimi Code | kimi |
Skills-based integration; installs into .kimi-code/skills/. --migrate-legacy moves old .kimi/skills/ installs to the new paths |
| Kiro CLI | kiro-cli |
Kiro CLI does not substitute $ARGUMENTS in file-based prompts, so Spec Kit ships a prose fallback at render time (see Manage prompts and issue #1926). Alias: --integration kiro |
| Lingma | lingma |
Skills-based integration; skills are installed automatically |
| Mistral Vibe | vibe |
|
| Oh My Pi | omp |
Installs slash commands into .omp/commands |
| opencode | opencode |
|
| Pi Coding Agent | pi |
Pi doesn't have MCP support out of the box, so taskstoissues won't work as intended. MCP support can be added via extensions |
| Qoder CLI | qodercli |
|
| Qwen Code | qwen |
|
| RovoDev | rovodev |
Generates .rovodev/skills/, prompt wrappers, and prompts.yml; runtime dispatch uses acli rovodev |
| SHAI (OVHcloud) | shai |
|
| Tabnine CLI | tabnine |
|
| Trae | trae |
Skills-based integration; skills are installed automatically |
| ZCode | zcode |
Skills-based integration; installs skills into .zcode/skills/ and invokes them as $speckit-<command> |
| Zed | zed |
Skills-based integration; installs skills into .agents/skills and invokes them as /speckit-<command> |
| Generic | generic |
Bring your own agent — use --integration generic --integration-options="--commands-dir <path>" for AI coding agents not listed above |
List Available Integrations
specify integration list
| Option | Description |
|---|---|
--catalog |
Also browse the catalog (built-in and community). Community integrations that are not built in are only shown here. |
Shows the built-in integrations, which one is currently installed, and whether each requires a CLI tool or is IDE-based. When multiple integrations are installed, the list marks the default integration separately from the other installed integrations. The list also shows whether each built-in integration is declared multi-install safe.
Search Available Integrations
specify integration search [query]
| Option | Description |
|---|---|
--tag |
Filter by tag |
--author |
Filter by author |
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.
Integration Info
specify integration info <integration_id>
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.
Install an Integration
specify integration install <key>
| Option | Description |
|---|---|
--script sh|ps |
Script type: sh (bash/zsh) or ps (PowerShell) |
--force |
Opt in to installing alongside integrations that are not declared multi-install safe |
--integration-options |
Integration-specific options (e.g. --integration-options="--commands-dir .myagent/cmds") |
Installs the specified integration into the current project. If another integration is already installed, the command only proceeds automatically when all involved integrations are declared multi-install safe. Otherwise, use switch to replace the default integration or pass --force to explicitly opt in to multi-install. If the installation fails partway through, it automatically rolls back to a clean state.
Installing an additional integration does not change the default integration. Use specify integration use <key> to change the default.
Note: All integration management commands require a project already initialized with
specify init. To start a new project with a specific agent, usespecify init <project> --integration <key>instead.
Version note: Controlled multi-install support was introduced in Spec Kit 0.8.5. If specify integration install <key> says another integration is already installed and only suggests switch or uninstall, check your local CLI with specify version and upgrade it. Running a one-shot command such as uvx --from git+https://github.com/github/spec-kit.git specify ... uses a temporary copy for that command only; it does not update the persistent specify executable on your PATH.
Uninstall an Integration
specify integration uninstall [<key>]
| Option | Description |
|---|---|
--force |
Remove files even if they have been modified |
Uninstalls the current integration (or the specified one). Spec Kit tracks every file created during install along with a SHA-256 hash of the original content:
- Unmodified files are removed automatically.
- Modified files (where you've made manual edits) are preserved so your customizations are not lost.
- Use
--forceto remove all integration files regardless of modifications.
Switch to a Different Integration
specify integration switch <key>
| Option | Description |
|---|---|
--script sh|ps |
Script type: sh (bash/zsh) or ps (PowerShell) |
--force |
Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default |
--refresh-shared-infra |
Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved) |
--integration-options |
Options for the target integration when it is not already installed |
If the target integration is not already installed, equivalent to running uninstall followed by install in a single step. In this mode, --force controls whether modified files from the removed integration are deleted. If the target integration is already installed, switch only changes the default integration, like use; in this mode, --force controls whether managed shared templates are overwritten while the default changes. --integration-options is rejected for already-installed targets because changing integration options requires reinstalling managed files; run upgrade <key> --integration-options ... first, then use <key>.
Use an Installed Integration
specify integration use <key>
| Option | Description |
|---|---|
--force |
Overwrite managed shared templates while changing the default |
Sets the default integration without uninstalling any other installed integrations. This also refreshes managed shared templates so command references match the new default integration's invocation style. Modified or untracked shared templates are preserved unless --force is used.
Upgrade an Integration
specify integration upgrade [<key>]
| Option | Description |
|---|---|
--force |
Overwrite files even if they have been modified |
--script sh|ps |
Script type: sh (bash/zsh) or ps (PowerShell) |
--integration-options |
Options for the integration |
Reinstalls an installed integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the default integration; if a key is provided, it must be one of the installed integrations. Detects locally modified files and blocks the upgrade unless --force is used. Stale files from the previous install that are no longer needed are removed automatically. Shared templates stay aligned with the default integration even when upgrading a non-default integration.
Report Integration Status
specify integration status
specify integration status --json
Reports the current project's integration status without changing files. The
status report includes the default integration, installed integrations,
multi-install safety, missing managed files, modified managed files, invalid
manifest paths, shared Spec Kit infrastructure health, unchecked manifests, and
the target integration for default-sensitive shared templates. The JSON form is
intended for CI and coding agents that need stable machine-readable status data;
it also reports the raw recorded integrations and the integration manifests that
were checked when state repair heuristics differ from the recorded file.
The command exits 0 when the report status is ok or warning; it exits 1
only when the report status is error. In JSON output, multi_install_safe
is null when no installed integration set can be evaluated, such as when the
integration state is missing, unreadable, lacks a valid recorded integration
list, or records no installed integrations.
Catalog Management
Integration catalogs control where the discovery commands (search and info) look for integrations. Catalogs are checked in priority order.
List Catalogs
specify integration catalog list
Shows the active catalog sources. Project-level sources (when configured) are removable by index; otherwise the active sources are shown as non-removable.
Add a Catalog
specify integration catalog add <url>
| Option | Description |
|---|---|
--name <name> |
Optional name for the catalog |
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).
Remove a Catalog
specify integration catalog remove <index>
Removes a project catalog source by its 0-based index in catalog list.
Catalog Resolution Order
Catalogs are resolved in this order (first match wins):
- Environment variable —
SPECKIT_INTEGRATION_CATALOG_URLoverrides all catalogs - Project config —
.specify/integration-catalogs.yml - User config —
~/.specify/integration-catalogs.yml - Built-in defaults — official catalog + community catalog
Integration-Specific Options
Some integrations accept additional options via --integration-options:
| Integration | Option | Description |
|---|---|---|
generic |
--commands-dir |
Required. Directory for command files |
kimi |
--migrate-legacy |
Migrate legacy .kimi/skills/ installs to .kimi-code/skills/ (including dotted→hyphenated skill naming, e.g. speckit.xxx → speckit-xxx) |
copilot |
--skills |
Scaffold commands as agent skills (speckit-<command>/SKILL.md under .github/skills/, invoked as /speckit-<command>) instead of the default legacy markdown mode (.github/agents/*.agent.md plus .github/prompts/*.prompt.md and a .vscode/settings.json merge). Without this flag, install warns that legacy markdown mode is deprecated. |
Example:
specify integration install generic --integration-options="--commands-dir .myagent/cmds"
Scaffold a New Integration
specify integration scaffold <key>
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).
| Option | Description |
|---|---|
--type |
Scaffold template to use: markdown (default), skills, toml, or yaml |
FAQ
Can I install multiple integrations in the same project?
Yes, but it is intended for team portability rather than the default workflow. Multiple integrations are allowed automatically only when the installed integration and the new integration are declared multi-install safe by Spec Kit. For other combinations, pass --force to acknowledge that multiple agents may see unrelated agent-specific instructions or commands.
Spec Kit tracks one default integration in .specify/integration.json with default_integration, all installed integrations with installed_integrations, per-integration runtime settings with integration_settings, and a dedicated integration_state_schema for future state migrations. The legacy integration field remains as an alias for the default integration.
Which integrations are multi-install safe?
An integration is multi-install safe when it uses a static, unique agent root and command directory, stable command invocation settings, and a separate install manifest whose managed files do not overlap another safe integration. Registry tests enforce those path and manifest invariants. Shared Spec Kit templates remain aligned to the single default integration.
The Isolation column below lists paths Spec Kit manages for that integration (skills/commands roots and any integration-owned rule files). It is not a full inventory of every file an agent may read.
Agent-context defaults are separate. The optional agent-context extension maps each integration to a default context file in extensions/agent-context/agent-context-defaults.json. Those defaults are independent of multi-install safety: several agents may share a root file such as AGENTS.md when the extension is enabled. Multi-install safety does not require a unique context file per safe integration.
The currently declared multi-install safe integrations are:
| Key | Isolation |
|---|---|
auggie |
.augment/commands, .augment/rules/specify-rules.md |
claude |
.claude/skills, CLAUDE.md |
cline |
.clinerules/workflows, .clinerules/specify-rules.md |
codebuddy |
.codebuddy/commands, CODEBUDDY.md |
codex |
.agents/skills, AGENTS.md |
cursor-agent |
.cursor/skills, .cursor/rules/specify-rules.mdc |
firebender |
.firebender/commands, .firebender/rules/specify-rules.mdc |
gemini |
.gemini/commands, GEMINI.md |
grok |
.grok/skills |
junie |
.junie/commands, .junie/AGENTS.md |
kilocode |
.kilocode/workflows, .kilocode/rules/specify-rules.md |
qodercli |
.qoder/commands, QODER.md |
qwen |
.qwen/commands, QWEN.md |
shai |
.shai/commands, SHAI.md |
tabnine |
.tabnine/agent/commands, TABNINE.md |
trae |
.trae/skills, .trae/rules/project_rules.md |
zcode |
.zcode/skills, ZCODE.md |
Integrations that share a command directory with another integration, require dynamic install paths such as --commands-dir, or merge shared tool settings are not declared safe by default. They can still be installed alongside another integration with --force.
What happens to my changes when I uninstall or switch?
Files you've modified are preserved automatically. Only unmodified files (matching their original SHA-256 hash) are removed. Use --force to override this.
How do I know which key to use?
Run specify integration list to see all available integrations with their keys, or check the Supported AI Coding Agents table above.
Do I need the AI coding agent installed to use an integration?
CLI-based integrations (like Claude Code, Gemini CLI) require the tool to be installed. IDE-based integrations (like Cursor) work through the IDE itself. Some agents like GitHub Copilot support both IDE and CLI usage. specify integration list shows which type each integration is.
When should I use upgrade vs switch?
Use upgrade when you've upgraded Spec Kit and want to refresh an installed integration's managed files. Use switch when you want to replace the current default with another integration; if the target is already installed, switch behaves like use.