Agent agnostic -- Keep agent-specific state out of .specify/

[ChristopherBull]

Running specify init --here --integration claude puts project decisions and developer preferences together in .specify/. Some files are needed by every collaborator: the constitution, templates, scripts and workflows. Other files, and parts of files, record which agent I chose. Because both live in the same folder, a team can't commit .specify/ without also committing one person's agent choice.

Files that aren't agent-agnostic after a clean init (Spec Kit v1.0.12.dev0):

• .specify/integration.json
  • "installed_integrations": ["claude"]
  • "integration_settings": { "claude": { ... } }
  • "integration": "claude", "default_integration": "claude"
• .specify/init-options.json
  • "ai": "claude"
  • "integration": "claude"
• .specify/integrations/claude.manifest.json

Spec Kit's specs, plans and constitution work with any agent, which is a big part of its appeal. In a shared repo, though, each contributor may use a different agent (Claude, Copilot, Gemini, Cursor and so on). These files would likely get committed, deliberately or accidentally, and If these files are committed:

• the next contributor who runs init with a different agent rewrites them, which causes churn and possible merge conflicts
• the repo implies that one agent is the default, when the choice is really personal (a company may decide on one agent, but any of their open source work would still invite contributions from people who may not use the same agent)
• teams have to work out the right .gitignore rules for themselves

Proposal:

1. Add the entries above to the generated .specify/.gitignore, alongside feature.json. It already ignores per-checkout state (active feature being developed), and this is a similar state.
2. Alternatively, move the per-agent state into a single local-only file such as .specify/local/.
3. Document which parts of .specify/ are meant to be committed and which are per-developer.

[mnriem]

Thanks for raising this. Spec Kit does support multiple agents in one project: after specify init --here --integration claude, you can run specify integration install gemini. Both remain installed, and adding Gemini does not change the default. This has been supported since 0.8.5; combinations not declared multi-install safe require --force. See the multiple-integrations FAQ.

That addresses a team whose contributors use different agents, but not quite the preference you describe. Spec Kit still has one project-wide default. specify integration use <key> changes shared state and templates, so independently choosing a local default can cause repository churn. That distinction is worth documenting and potentially supporting with a per-checkout override.

I would avoid ignoring all three files without that design change: integration.json records installed integrations, and the manifests track managed files for safe uninstall. init-options.json also contains settings beyond the agent choice.

[ChristopherBull]

Thank you for confirming. That is exactly my point; To avoid churn through collaboration, and to reduce how opinionated the SpecKit install is (with agent integrations that are unsafe to collocate).

[mnriem]

An integration is only unsafe for multi install if it edits any file that would be shared between the ones you use. Most generally reuse of shared files only really happens when you use agent-context extension which is not installed by default. While I agree we could make it even easier that would have to be a gradual process to get there. Thanks for the feedback!

[dishantsethi]

@ChristopherBull We ran into the same churn on a team with mixed Claude Code and Copilot users. What helped was splitting shared decisions from personal tool choices.

Anything agent-specific is gitignored and regenerated by a small bootstrap script each dev runs after cloning. We kept one short, agent-neutral context file in git (via enactapp.io) that the specs point to. That way every agent starts from the same project facts, whatever wrapper it runs in.

[mnriem]

I would love suggestions on how you think we should solve this

[markuswondrak]

This lines up with something I wrote about recently: Managing Spec-Kit Extensions, Presets, Workflows, and Bundles as Packages. The article is about extensions, presets, workflows and bundles, but I think the same model applies to integrations.

The underlying issue is that .specify/ holds several kinds of state that have different lifecycles:

• Project intent: what the team decided and wants shared.
• Installed artifacts and their installation records: the output of an install step, which can be rebuilt.
• Machine-local state: personal preferences and per-checkout pointers.

Right now integration state mixes all three, sometimes inside a single file. That's why no simple .gitignore rule works. Once each piece of state has a clear category, the commit-or-ignore question mostly answers itself.

One principle I'd highlight: an installation record should always share the fate of the files it describes. If those files are committed, commit the record. If they're per-developer, the record is too. That keeps uninstall safe while still allowing a per-developer agent choice.

This seems like part of the broader separation asked for in #2612 and #2681, so it might be worth solving there once rather than case by case.

AI disclosure: This comment was drafted with OpenCode (model: claude-opus-5.5, human-supervised) on behalf of @markuswondrak and reviewed before posting.