Repository navigation
[Feature]: Add specify integration status reporting command #2671
Description
Problem Statement
Spec Kit now supports richer integration state: default integration selection,
controlled multi-install, per-integration settings, manifests, shared
infrastructure, and integration-specific command/context directories.
When something looks wrong, users and coding agents still have to infer project
state by manually inspecting files such as .specify/integration.json,
.specify/integrations/*.manifest.json, and generated agent command
directories. This makes it hard to distinguish between:
- an outdated CLI;
- a missing or malformed integration state file;
- a default integration mismatch;
- missing or modified managed files;
- an unsafe multi-install combination;
- stale files left behind after an integration upgrade or switch.
A first-class read-only status report would make integration issues easier to
report, debug, and safely fix.
Proposed Solution
Add a status reporting command:
specify integration statusThe command should inspect the current project and print a concise health report
for integration state.
Example output:
Integration status: OK
Default integration: claude
Installed integrations: claude, codex
Multi-install safe: yes
Shared templates aligned to: claude
Modified managed files: none
Missing managed files: none
For unhealthy state, it should explain the problem and suggest the safest next
command, for example specify integration use <key>,
specify integration upgrade <key>, or specify integration upgrade --force
only when appropriate.
Naming
The command name is status based on maintainer feedback that this is reporting
project integration state rather than performing repair.
Suggested Checks
- Project contains
.specify/and is a Spec Kit project. .specify/integration.jsonexists and matches the expected schema.- Default integration is set and is among installed integrations.
- Installed integrations exist in the registry for the running CLI.
- Per-integration settings are readable.
- Manifest files exist for installed integrations where expected.
- Manifest-tracked files are present.
- Manifest-tracked files that changed locally are reported, not overwritten.
- Shared infrastructure manifest is readable where expected.
- Installed integrations are multi-install safe, or unsafe combinations are clearly reported.
- Command/context directories do not have obvious collisions between installed integrations.
JSON Output
A machine-readable form would be useful for coding agents and CI:
specify integration status --jsonPotential shape:
{
"status": "ok",
"default_integration": "claude",
"installed_integrations": ["claude", "codex"],
"multi_install_safe": true,
"findings": []
}Acceptance Criteria
-
specify integration statusexits 0 for a healthy Spec Kit project. - It reports the default integration and installed integrations.
- It reports malformed or missing
.specify/integration.jsonwithout a traceback. - It reports missing manifest-tracked files.
- It reports modified managed files without changing them.
- It reports unsafe multi-install combinations.
- It gives non-destructive guidance first (
use/upgradebeforeswitch/uninstall). -
--jsonemits stable machine-readable status data. - Tests cover healthy state, missing state, malformed state, missing files, modified files, and unsafe combinations.
Suggested Tests
pytest tests/integrations/test_integration_subcommand.py tests/integrations/test_manifest.py -vContext
This is a follow-up to the integration discoverability and multi-install work
tracked around #2498 / #2519 / #2548 / #2549 / #2574. It is separate from the
active specify self upgrade work in #2475.
Activity
PascalThuet commentedon May 21, 2026
Quick duplicate check:
I searched for existing issues/PRs around
doctor,diagnostic,integration state,integration.json,manifest, and missing/modified managed files.Related but not duplicate:
integration upgradeintegration switch#2375 fixed shared infra refresh duringintegration switchThose improve specific install/upgrade paths, but none add a read-only diagnostic command that reports project integration health across state, manifests, missing/modified managed files, multi-install safety, and optional JSON output.
So I think this issue is still useful as a distinct
specify integration doctorproposal.mnriem commentedon May 26, 2026
Other than that I would probably prefer 'status' as it is reporting, go for it!
[-][Feature]: Add `specify integration doctor` diagnostic command[/-][+][Feature]: Add `specify integration status` reporting command[/+]PascalThuet commentedon May 26, 2026
@mnriem i updated the PR according your preference