Speckit integrations in version control

[chuangmaster]

I have a project with multiple integrations (agents) such as agy, claude and codex. The configuration settings for these integrations are tracked in the same version control.

However, when team members switch between different integrations, speckit automatically generates a lot of skills and settings files, which leads to a lot of "trash" or unwanted commits in the repository.

Is there a recommended way to handle this other than using .gitignore?

(By the way, agy cannot be installed via multi-install...)

[mnriem]

Thanks for raising this. Your observations are correct, although the generated files are currently considered project configuration rather than disposable output, so the expected model is generally to commit the integrations that the team supports.

For integrations with separate output directories, the recommended workflow is to install them once and then select between them with use:

specify integration install claude
specify integration install codex
specify integration use claude
# later
specify integration use codex

switch is primarily the replacement operation: if its target is not already installed, it uninstalls the current integration and installs the new one. That explains the larger delete/regenerate diffs.

The agy case is a real limitation. Both agy and Codex manage .agents/skills, so they cannot be considered independently multi-install safe. You can bypass the check with:

specify integration install agy --force

but when Codex is also installed this acknowledges overlapping ownership rather than making the combination safe. The current safety flag is also integration-wide, not pair-specific, so agy requires --force even alongside an integration such as Claude whose directory does not overlap.

Also, selecting another default integration may still change .specify/integration.json, shared templates, and extension or preset artifacts. There is not currently a fully user-local integration selection that guarantees a clean working tree for a team whose members independently use different agents.

So .gitignore is one option if the team deliberately wants agent configuration to remain local, but it means those integrations are no longer reproducible from the repository. Improving support for shared output directories or adding a user-local active-agent preference would be useful enhancements here.

AI disclosure: Drafted and posted on behalf of @mnriem with GitHub Copilot using GPT-5.6 Sol, default settings, human-supervised; repository/release assessment and response drafting.

[chuangmaster]

Thanks for the detailed clarification! It makes sense that these are currently treated as shared project configuration rather than disposable output.

For teams where developers independently prefer different local agents (e.g., mixing Claude and agy/Codex), having .specify/integration.json and generated skill files constantly churn in shared branches can still be quite noisy. I really hope a user-local active-agent preference or native .gitignore workflow template gets prioritized in future enhancements. Thanks again for your sharing.

[markuswondrak]

I actually had some thought about this as well and came up with my own "strict vcs policy", that tries only to commit those files that are not generated via install (s. @mnriem answer).

https://github.com/markuswondrak/spec-kit-skill

I also wrote about these thoughts some time ago: https://markus.wondrax.cloud/articles/spec-kit-organization.html

[mnriem]

We currently have #5030 in flight that will allow you to scaffold a project without an active integration. This will allow you to install/uninstall a specific integration which means you would not need to commit those. The .specify directory will still be required to commit as it contains your extensions/presets/bundles/workflows/steps