Integration install/switch can leave stale vendored .specify shared scripts that break newer agent integrations (e.g. pi)

[kseikyo]

Summary

A project can end up with a current integration wrapper but a stale vendored copy of .specify/scripts/bash/update-agent-context.sh (and related shared scripts). In that state, newer integrations like pi appear installed and supported by the CLI, but update-context still fails inside the project because the repo-local shared script is older and does not recognize the integration key.

What I observed

In a project initialized with the pi integration:

• specify integration list showed pi as installed and supported
• .specify/integrations/pi/scripts/update-context.sh existed and delegated to:
  • .specify/scripts/bash/update-agent-context.sh pi
• but the repo-local .specify/scripts/bash/update-agent-context.sh was an older vendored copy that did not include pi in its supported agent list

Result:

.specify/integrations/pi/scripts/update-context.sh
# ...
# ERROR: Unknown agent type 'pi'

The installed CLI/core pack already supported pi; the failure was caused by the project's vendored shared scripts being out of sync with the CLI version.

Why this is surprising

A user can reasonably expect one of these to repair the project:

• specify integration install pi
• specify integration switch pi
• reinstalling/upgrading specify

But the shared infra installer explicitly merges missing files without overwriting existing ones. So if .specify/scripts/bash/update-agent-context.sh already exists, it is preserved even if it is stale. That leaves the project in a partially upgraded state:

• integration metadata/wrapper: new
• shared vendored .specify/scripts/*: old

Impact

• update-context can fail for newly added integrations
• behavior can diverge from the installed specify CLI version
• users may think the integration itself is broken when the real issue is stale shared infra in the project

Reproduction shape

I don't have a minimal public repro repo, but the failure mode is roughly:

1. Create/init a project with an older vendored .specify/scripts/bash/update-agent-context.sh
2. Upgrade/install a newer specify CLI that supports a new integration such as pi
3. Have the project contain the current pi integration wrapper under .specify/integrations/pi/scripts/update-context.sh
4. Run:

   .specify/integrations/pi/scripts/update-context.sh

5. Observe Unknown agent type 'pi' from the stale repo-local shared script

Expected behavior

Spec Kit should provide a supported way to avoid or repair this drift. Examples:

1. Drift detection

   • warn when project vendored shared infra is older/incompatible with the installed CLI/integration set

2. Refresh command or flag

   • e.g. a supported command to refresh shared .specify/scripts and templates from the current core pack
   • or a --refresh-shared-infra / --overwrite-shared-infra option for integration install/switch

3. Compatibility guard

   • before running an integration wrapper, detect when the delegated shared script does not support the current integration key and emit a more actionable error

Related issues

This seems adjacent to, but not the same as:

• Switch agents without re-initializing the project #877 (switch agents without re-initializing the project)
• Rewrite AGENTS.md for integration subpackage architecture #2067 (integration architecture / docs)
• [Bug]: Script update-agent-context.sh is updating copilot-instructions.md at wrong path #2016 / update-agent-context.sh script fails with sed expression errors and incorrect template path #293 / other update-agent-context bugs

Those cover switching/docs/script bugs, but not the specific stale vendored shared infra causing new integrations to fail despite CLI support case.

Suggested direction

At minimum, it would help to document clearly that integration install/switch does not overwrite existing shared infra and can leave stale project-local .specify/scripts/* in place. A first-class refresh/drift-check mechanism would be even better.

[kseikyo]

A couple of follow-ups after reading CONTRIBUTING.md and the issue templates:

1. AI disclosure: this issue was researched and drafted with AI assistance, then reviewed/validated by me against a real local failure using specify CLI, the installed core-pack source, and the project-local vendored .specify files.

2. Potential product direction: one way to make this class of problem less painful would be better support for multiple agents/integrations in one project, rather than assuming a single active harness/integration owns the project-local wiring. In the failure I hit, the stale shared infra mismatch was especially confusing because the project had current integration-specific Pi files alongside older shared scripts.

I realize multi-agent support is a broader feature than this bug, so I’m not suggesting it has to be solved here. But if Spec Kit eventually supports multiple coexisting integrations more explicitly, it may be worth designing drift detection / shared-infra refresh around that model instead of a strictly single-integration one.