[Feature]: Deprecate and remove multi-install in favor of fast agent integration switching #5040

Problem and rationale

Spec Kit already supports multiple agents through a shared project foundation. Specifications, plans, tasks, constitution, installed extensions, presets, and workflow definitions belong to the project. Changing agents does not require reinstalling that process.

The agent-specific commands and skills are a rendered interface to that foundation. Regenerating this interface is inexpensive: 140 measured specify integration switch operations completed successfully, with a median of 0.501 seconds and a maximum of 0.880 seconds. With both first-party process extensions and both bundled presets installed, the median was 0.676 seconds.

For a developer choosing one agent per checkout, multi-install avoids an initial subsecond operation and occasional similarly inexpensive switches. In exchange, it introduces persistent coexistence state, installed-versus-default semantics, safety declarations, overlap checks, additional lifecycle branches, and cross-integration tests.

The proposed simplification is:

Keep multi-agent support through one shared project foundation. Select one agent integration per checkout and regenerate its interface when needed. Retire concurrent installation of multiple agent integrations.

Evidence

Runtime validation used landed commit a055f62517a86cd316770a67b8003cf807f4d795, Specify CLI 1.2.3.dev0, and Python 3.13.16 on macOS arm64.

All 20 directed transitions between none, copilot, claude, codex, and opencode were exercised across seven configurations: core only; bug; assess; both extensions; lean; constitution-sync; and both extensions with both presets.

All 140 switches passed, without --force or extension/preset reinstallation. Checks verified generated command placement, old-command cleanup, rendered preset content, single-integration state, and preservation of existing project artifacts and user-owned files.

These were real CLI subprocess executions, not mocked lifecycle tests. They did not execute the resulting prompts through the four agents. Timings describe this environment, not a universal performance guarantee.

A multi-install control produced 48 command entry points versus 18 for the equivalent single-active-integration configuration. Inactive integrations received only core commands, not the complete extension/preset configuration. The Copilot-containing combination required --force and reported unsafe-multi-install.

Preset overrides also generated modified-managed-file warnings during single-integration switching. Rendering and cleanup passed; this diagnostic issue should not be presented as warning-free behavior.

The original implementation, github/spec-kit#2389, changed 30 files:

Its shared infrastructure and safety improvements are not all attributable exclusively to coexistence and must not be removed indiscriminately.

Follow-up work includes safety declarations, guidance, documentation synchronization, and dedicated test optimization. User reports include non-active-agent rendering and extension availability: github/spec-kit#2948, github/spec-kit#4888, and github/spec-kit#5002.

Switching also requires maintenance. The distinction is that multi-install adds coexistence obligations alongside the existing switching lifecycle rather than replacing it.

Proposed solution

Support exactly one selected integration per checkout, including none for shared scaffolding without generated agent commands.

Retain specify integration switch <key> as the supported way to change agents. Preserve installed extensions, presets, workflows, authored artifacts, and user-owned files.

Retire coexistence-specific state and behavior, including additional-install safety gates and the distinction between installed integrations and a default integration. Review integration use, safety metadata, scaffolding, reporting, external adapter contracts, and documentation as part of the staged compatibility work.

Preserve unrelated behavior such as modified-file protection, shared-infrastructure safety, trusted external adapter handling, and single-integration installation and upgrade.

Four-stage rollout

1. Deprecation warnings and documentation: Document fast agent integration switching as the existing replacement and warn when creating or using multi-install configurations, with actionable migration guidance using existing capabilities. Preserve current behavior, defaults, and compatibility. Do not introduce a new migration command, activation prerequisite, migration subsystem, or opt-in mode; do not remove integrations or alter project selection automatically.
2. Explicit temporary opt-out for integration use: Make specify integration use <key> warn and stop with a non-zero exit status before changing files, settings, or the selected integration. The message directs users to specify integration switch <key> and explains that specify integration use <key> --opt-out temporarily permits the existing legacy behavior. With --opt-out, retain the deprecation warning and perform the existing use operation; do not silently call switch, uninstall integrations, or suppress the warning. The opt-out is an explicit per-invocation acknowledgment, not persisted configuration, and --force is not a substitute for it. This behavior change is not part of stage one.
3. Removal: Remove multi-install support, coexistence-specific state and lifecycle machinery, and the temporary --opt-out after adequate announced release/adoption time. Unmigrated configurations receive actionable migration errors rather than arbitrary integration selection or silent cleanup. Preserve shared safety and rendering functionality. There is no separate additional-install enforcement/legacy-opt-out stage.
4. Documentation cleanup: Remove obsolete multi-install instructions, temporary --opt-out guidance, and transitional examples from current documentation and CLI help after removal. Keep the single-integration and fast-switching guidance accurate. Preserve historical release notes rather than rewriting history; this stage does not introduce further runtime behavior changes.

No specific release versions are committed. Separate PRs are not themselves compatibility windows.

Migration guidance belongs to deprecation and uses existing lifecycle commands: during stage one, deliberately select the integration to retain with specify integration use <key>; during stage two, this legacy operation requires the explicit temporary --opt-out. Explicitly uninstall other installed integrations without --force; once only one remains, use specify integration switch <key> to change agents, including none. switch alone does not consolidate an existing multi-install project. Remove only validated managed files belonging to other integrations, preserve user modifications and shared process packages/artifacts, and report retained files or conflicts explicitly. Invalid or ambiguous state must not trigger an arbitrary fallback. This is guidance for the existing capabilities, not a request for a new migration command or subsystem.

Acceptance criteria

• All four rollout stages have documented compatibility behavior and an adequate announced transition period.
• The supported model has one selected integration per checkout, including none.
• Switching preserves shared process packages and authored artifacts while rendering the selected agent's core, extension, and preset interface.
• Existing single-integration projects remain compatible.
• Stage-one deprecation warnings provide an actionable, documented migration path using existing lifecycle commands, without new migration machinery or changes to behavior/defaults.
• In stage two, integration use <key> without --opt-out warns and exits non-zero without changing files, settings, or the selected integration, including when --force is supplied.
• In stage two, integration use <key> --opt-out retains its deprecation warning and existing selection, validation, and file-handling behavior; it does not invoke switching or remove other integrations.
• Stage-two help, documentation, and warning text explain the temporary, per-invocation opt-out and direct users to integration switch; tests cover refusal without acknowledgment, allowed legacy use, and no persisted opt-out.
• Migration preserves user-owned and modified files and reports conflicts without silent deletion or arbitrary selection.
• Lifecycle commands, reporting, machine-readable contracts, adapter compatibility, and directly related documentation consistently reflect each rollout stage.
• Coexistence-specific code and tests are removed only when compatibility is retired; shared safety and rendering functionality remain intact.
• Stage three removes multi-install and the temporary opt-out without a separate additional-install enforcement stage; stage four removes obsolete guidance and transitional examples from current documentation/help while preserving historical release notes.
• Positive, negative, and regression coverage demonstrates switching, migration, invalid state, extension/preset preservation, and customized-file handling.
• Runtime evidence includes the four validated agents, none, both process extensions, and both bundled presets.
• Removal is gated on compatibility evidence and transition time, not solely on measured speed or line count.

Alternatives and scope

An agent integration is an adapter to the shared Spec Kit process, not a separate installation of that process. Switching preserves project artifacts and installed process customizations while regenerating the selected agent's interface. Team portability does not require multi-install.

This proposal establishes one selected integration per checkout as the supported architecture. It does not remove support for any agent, extensions, presets, or shared workflows. Teams can select different integrations in their individual checkouts or isolated worktrees.

This is a tracking issue for staged PRs, not an instruction to implement every stage at once. It is independent of the artifact-layout migration in github/spec-kit#5037.

AI disclosure

Drafted and filed on behalf of @mnriem using GitHub Copilot App, powered by GPT-6.1 Sol (gpt-6.1-sol), through human-directed interactive discussion. The agent authored and executed the runtime measurement harness, inspected repository history and related issues/PRs, and drafted this proposal. The user reviewed the draft, directed revisions, and authorized filing upstream. Reasoning-effort setting was unavailable to report. No product implementation changes were made when this issue was originally filed.

An earlier rollout revision was made on the user's explicit instruction by GitHub Copilot App, powered by GPT-6.1 Sol (gpt-6.1-sol), acting autonomously in a coordinated child session. That revision removed the unnecessary standalone migration-opt-in stage, made existing-command migration guidance part of deprecation, and changed the rollout and acceptance criteria from four stages to three. Reasoning-effort setting was unavailable to report.

The user subsequently selected warn-and-stop behavior for integration use unless --opt-out is supplied and explicitly authorized documenting it as step two, with removal as step three and documentation cleanup as step four. GitHub Copilot App, powered by GPT-6.1 Sol (gpt-6.1-sol), drafted this issue-only update through human-directed interactive discussion, including matching guidance and acceptance criteria. This authorization does not include implementing stage two, changing the stage-one PR, or closing the issue. Reasoning-effort setting was unavailable to report.